ci: improve release workflow and bump obikmer to v1.1.37

Replace inline `docker run` with explicit container lifecycle management to improve isolation and verify exit statuses. Bump `obikmer` crate version to 1.1.37. Add debug logging for sparse hit structure memory tracking, update chunk memory documentation to reflect the Findere rework, and clarify `BYTES_PER_KMER_PER_GENOME` as a pathological bound for safety tuning.

.gitea/workflows/ci.yml

@@ -1,9 +1,8 @@
 name: CI
 
 on:
-  push:
-    branches: ['**']
   pull_request:
+    branches: ['main']
 
 jobs:
   build:

.gitea/workflows/release.yml

@@ -3,10 +3,35 @@ name: Release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 
 jobs:
-  build-linux-static:
+  create-release:
+    runs-on: ubuntu-latest
+    outputs:
+      release_id: ${{ steps.create.outputs.release_id }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Create Gitea release
+        id: create
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+          TAG: ${{ github.ref_name }}
+        run: |
+          sudo apt-get update -qq && sudo apt-get install -y -qq jq
+          body=$(git for-each-ref --format='%(contents)' "refs/tags/$TAG")
+          release_id=$(curl -s -X POST \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -H "Content-Type: application/json" \
+            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\",\"body\":$(echo "$body" | jq -Rs .)}" | jq -r '.id')
+          echo "release_id=$release_id" >> $GITHUB_OUTPUT
+
+  build-linux-x86_64:
+    needs: create-release
     runs-on: ubuntu-latest
     defaults:
       run:
@@ -14,13 +39,22 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Rust + musl target
+      - name: Install Rust + zigbuild
         run: |
           curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable
           echo "$HOME/.cargo/bin" >> $GITHUB_PATH
-          sudo apt-get update -qq && sudo apt-get install -y -qq musl-tools jq
+          sudo apt-get update -qq && sudo apt-get install -y -qq jq
+          pip install ziglang --quiet --break-system-packages
+          $HOME/.cargo/bin/cargo install cargo-zigbuild
           $HOME/.cargo/bin/rustup target add x86_64-unknown-linux-musl
 
+      - name: Create musl C/C++ wrappers
+        run: |
+          ZIG=$(python3 -c "import ziglang, os; print(os.path.join(os.path.dirname(ziglang.__file__), 'zig'))")
+          printf '#!/bin/sh\nexec "%s" cc -target x86_64-linux-musl "$@"\n' "$ZIG" | sudo tee /usr/local/bin/x86_64-linux-musl-gcc > /dev/null
+          printf '#!/bin/sh\nexec "%s" c++ -target x86_64-linux-musl "$@"\n' "$ZIG" | sudo tee /usr/local/bin/x86_64-linux-musl-g++ > /dev/null
+          sudo chmod +x /usr/local/bin/x86_64-linux-musl-gcc /usr/local/bin/x86_64-linux-musl-g++
+
       - name: Cache cargo registry
         uses: actions/cache@v4
         with:
@@ -32,25 +66,62 @@ jobs:
           restore-keys: linux-musl-cargo-
 
       - name: Build static binary
-        run: cargo build --release --target x86_64-unknown-linux-musl
+        env:
+          PKG_CONFIG_ALLOW_CROSS: "1"
+        run: cargo zigbuild --release --target x86_64-unknown-linux-musl
 
-      - name: Prepare artifact
+      - name: Prepare and upload artifact
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+          RELEASE_ID: ${{ needs.create-release.outputs.release_id }}
         run: |
           mkdir -p /tmp/dist
           cp target/x86_64-unknown-linux-musl/release/obikmer /tmp/dist/obikmer-linux-x86_64
           strip /tmp/dist/obikmer-linux-x86_64
-
-      - name: Create Gitea release and upload binary
-        env:
-          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
-          TAG: ${{ github.ref_name }}
-        run: |
-          release_id=$(curl -s -X POST \
-            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases" \
-            -H "Authorization: token $GITEA_TOKEN" \
-            -H "Content-Type: application/json" \
-            -d "{\"tag_name\":\"$TAG\",\"name\":\"$TAG\"}" | jq -r '.id')
           curl -s -X POST \
-            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/$release_id/assets" \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/$RELEASE_ID/assets" \
             -H "Authorization: token $GITEA_TOKEN" \
             -F "attachment=@/tmp/dist/obikmer-linux-x86_64"
+
+  build-macos-arm64:
+    needs: create-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Login to registry
+        run: echo "${{ secrets.REGISTRYTOKEN }}" | docker login registry.metabarcoding.org -u ${{ secrets.REGISTRYUSER }} --password-stdin
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            src/target
+          key: macos-arm64-cargo-${{ hashFiles('src/Cargo.lock') }}
+          restore-keys: macos-arm64-cargo-
+
+      - name: Build macOS binary
+        run: |
+          CID=$(docker create \
+            -w /src/src \
+            registry.metabarcoding.org/cibuilder/rustcrossosx:latest \
+            cargo build --release --target aarch64-apple-darwin --no-default-features)
+          docker cp . "$CID:/src"
+          docker start -a "$CID"
+          STATUS=$(docker wait "$CID")
+          mkdir -p /tmp/dist
+          docker cp "$CID:/src/src/target/aarch64-apple-darwin/release/obikmer" /tmp/dist/obikmer-macos-arm64
+          docker rm "$CID" > /dev/null
+          [ "$STATUS" -eq 0 ]
+
+      - name: Prepare and upload artifact
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+          RELEASE_ID: ${{ needs.create-release.outputs.release_id }}
+        run: |
+          curl -s -X POST \
+            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/$RELEASE_ID/assets" \
+            -H "Authorization: token $GITEA_TOKEN" \
+            -F "attachment=@/tmp/dist/obikmer-macos-arm64"

.gitignore

@@ -8,14 +8,18 @@ data-stress
 *.pb
 ./**/*.json
 *.bin
+*.log
 Betula_exilis--IGA-24-33
 benchmark/genomes
 benchmark/simulated_data
 benchmark/specimen_index_presence
 benchmark/specimen_index_count
 benchmark/global_index_presence
+benchmark/all_specific
 benchmark/global_index_count
 benchmark/stats
 benchmark/reference_index
+benchmark/reference_dist
+benchmark/obikmer_dist
 benchmark/specific_index_count
 benchmark/specific_index_presence

Makefile

@@ -86,9 +86,13 @@ bump-version:
 
 .PHONY: release
 release: bump-version
-	@new_version=$$(grep '^version = ' $(CARGO_TOML) | head -n 1 | sed 's/version = "\(.*\)"/\1/'); \
-	git tag "v$$new_version"
 	@jj auto-describe
 	@jj git push --change @
 	@new_version=$$(grep '^version = ' $(CARGO_TOML) | head -n 1 | sed 's/version = "\(.*\)"/\1/'); \
+	git_hash=$$(jj log -r @ --no-graph -T 'commit_id'); \
+	commits=$$(jj log -r 'latest(tags())..@' --no-graph -T 'description ++ "\n"' 2>/dev/null || \
+	           jj log --no-graph -T 'description ++ "\n"' --limit 30); \
+	notes=$$(printf 'Write concise markdown release notes for obikmer (a Rust kmer genomics tool). Be technical and direct. Base them strictly on these commit messages:\n\n%s' "$$commits" | aichat 2>/dev/null); \
+	tag_msg="$${notes:-Release v$$new_version}"; \
+	git tag -a "v$$new_version" -m "$$tag_msg" "$$git_hash" && \
 	git push origin "v$$new_version"

benchmark/Makefile

@@ -10,6 +10,23 @@ GENOMES := $(wildcard genomes/*.fna.gz)
 -include deps.mk
 
 REF_NPZS              := $(SPECIMENS:%=reference_index/%.npz)
+REF_DIST_CSVS         := $(addprefix reference_dist/, \
+	shared_kmers.csv hamming_dist.csv jaccard_dist.csv \
+	bray_curtis_dist.csv relfreq_bray_curtis_dist.csv \
+	euclidean_dist.csv relfreq_euclidean_dist.csv \
+	hellinger_dist.csv hellinger_euclidean_dist.csv)
+OBIKMER_PRESENCE_DIST := $(addprefix obikmer_dist/presence/, \
+	jaccard_dist.csv jaccard_shared.csv jaccard_nj.nwk \
+	hamming_dist.csv hamming_nj.nwk)
+OBIKMER_COUNT_DIST    := $(addprefix obikmer_dist/count/, \
+	jaccard_dist.csv jaccard_shared.csv jaccard_nj.nwk \
+	bray_curtis_dist.csv bray_curtis_nj.nwk \
+	relfreq_bray_curtis_dist.csv relfreq_bray_curtis_nj.nwk \
+	euclidean_dist.csv euclidean_nj.nwk \
+	relfreq_euclidean_dist.csv relfreq_euclidean_nj.nwk \
+	hellinger_dist.csv hellinger_nj.nwk \
+	hellinger_euclidean_dist.csv hellinger_euclidean_nj.nwk)
+DIST_COMPARISON       := stats/dist_comparison/summary.csv
 PRESENCE_DONE         := $(SPECIMENS:%=specimen_index_presence/%/index.done)
 PRESENCE_STATS        := $(SPECIMENS:%=stats/indexing_presence/%.stats)
 COUNT_DONE            := $(SPECIMENS:%=specimen_index_count/%/index.done)
@@ -24,7 +41,9 @@ SIMULATED_READS := $(foreach s,$(SPECIMENS),simulated_data/$(subst --,/,$s)/read
 
 .NOTPARALLEL:
 
-.PHONY: all simulate reference \
+.PHONY: all simulate reference reference_dist \
+        obikmer_dist obikmer_dist_presence obikmer_dist_count \
+        dist_comparison \
         index_presence index_count \
         aggregate_index_presence aggregate_index_count \
         merge_presence merge_count \
@@ -39,7 +58,8 @@ verify_merge_count:    stats/verify_merge_count/current.csv
 
 all: aggregate_verify_presence aggregate_verify_count \
      verify_merge_presence verify_merge_count \
-     aggregate_filter_presence aggregate_filter_count
+     aggregate_filter_presence aggregate_filter_count \
+     dist_comparison
 
 # ── dependency file ───────────────────────────────────────────────────────────
 
@@ -62,6 +82,72 @@ reference_index/%.npz:
 
 reference: $(REF_NPZS)
 
+# ── reference distance matrices ───────────────────────────────────────────────
+
+$(REF_DIST_CSVS) &: $(REF_NPZS) build_reference_dist.py
+	$(VENV_PY) build_reference_dist.py
+
+reference_dist: $(REF_DIST_CSVS)
+
+# ── obikmer distance (presence index) ────────────────────────────────────────
+
+$(OBIKMER_PRESENCE_DIST) &: global_index_presence/index.done $(BINARY)
+	mkdir -p obikmer_dist/presence
+	$(BINARY) distance \
+		--output obikmer_dist/presence/jaccard \
+		--metric jaccard --shared-kmers --nj \
+		global_index_presence
+	$(BINARY) distance \
+		--output obikmer_dist/presence/hamming \
+		--metric hamming --nj \
+		global_index_presence
+
+obikmer_dist_presence: $(OBIKMER_PRESENCE_DIST)
+
+# ── obikmer distance (count index) ───────────────────────────────────────────
+
+$(OBIKMER_COUNT_DIST) &: global_index_count/index.done $(BINARY)
+	mkdir -p obikmer_dist/count
+	$(BINARY) distance \
+		--output obikmer_dist/count/jaccard \
+		--metric jaccard --shared-kmers --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/bray_curtis \
+		--metric bray-curtis --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/relfreq_bray_curtis \
+		--metric relfreq-bray-curtis --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/euclidean \
+		--metric euclidean --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/relfreq_euclidean \
+		--metric relfreq-euclidean --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/hellinger \
+		--metric hellinger --nj \
+		global_index_count
+	$(BINARY) distance \
+		--output obikmer_dist/count/hellinger_euclidean \
+		--metric hellinger-euclidean --nj \
+		global_index_count
+
+obikmer_dist_count: $(OBIKMER_COUNT_DIST)
+
+obikmer_dist: obikmer_dist_presence obikmer_dist_count
+
+# ── distance comparison ───────────────────────────────────────────────────────
+
+$(DIST_COMPARISON): $(REF_DIST_CSVS) $(OBIKMER_PRESENCE_DIST) $(OBIKMER_COUNT_DIST) compare_all_dist.py
+	$(VENV_PY) compare_all_dist.py --out $(DIST_COMPARISON)
+
+dist_comparison: $(DIST_COMPARISON)
+
 # ── per-specimen indexing ─────────────────────────────────────────────────────
 # Prerequisites (reads → index.done + .stats) are in deps.mk.
 

benchmark/build_reference_dist.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Compute reference pairwise distance matrices from per-specimen .npz kmer indexes.
+
+Reads all .npz files in reference_index/ (each containing sorted uint64 `kmers`
+and uint32 `counts`), computes all distance metrics supported by `obikmer distance`,
+and writes one CSV per metric to reference_dist/.
+
+Output CSV format matches `obikmer distance --output`:
+  - first row: "genome", then specimen names
+  - subsequent rows: specimen name, then float or int values
+
+Metrics written
+  jaccard_dist.csv          Jaccard distance (presence/absence)
+  shared_kmers.csv          Shared-kmer count matrix (intersection size)
+  bray_curtis_dist.csv      Bray-Curtis dissimilarity (raw counts)
+  relfreq_bray_curtis_dist.csv  Bray-Curtis on relative frequencies
+  euclidean_dist.csv        Euclidean distance (raw counts)
+  relfreq_euclidean_dist.csv    Euclidean distance on relative frequencies
+  hellinger_dist.csv        Hellinger distance
+  hellinger_euclidean_dist.csv  Euclidean distance in Hellinger space
+"""
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+
+# ── pairwise helpers ──────────────────────────────────────────────────────────
+
+def shared_indices(a_kmers: np.ndarray, b_kmers: np.ndarray):
+    """Return index arrays (idx_a, idx_b) for kmers present in both sets.
+
+    Both arrays must be sorted uint64. Uses searchsorted: O(|B| log |A|).
+    """
+    pos = np.searchsorted(a_kmers, b_kmers)
+    pos = np.clip(pos, 0, len(a_kmers) - 1)
+    mask = a_kmers[pos] == b_kmers
+    idx_b = np.where(mask)[0]
+    idx_a = pos[idx_b]
+    return idx_a, idx_b
+
+
+def pairwise_stats(specimens: list[dict]) -> dict[str, np.ndarray]:
+    """Compute all pairwise distance matrices at once.
+
+    Returns a dict metric_name → ndarray (n×n float64 or int64).
+    Each specimen dict has keys: name, kmers, counts.
+    """
+    n = len(specimens)
+
+    # Pre-compute per-specimen scalars
+    kmer_counts = np.array([len(s['kmers'])  for s in specimens], dtype=np.uint64)
+    count_sums  = np.array([s['counts'].sum() for s in specimens], dtype=np.uint64)
+
+    # Per-specimen sum-of-squares (for Euclidean decomposition)
+    sq_sums     = np.array([(s['counts'].astype(np.float64) ** 2).sum() for s in specimens])
+
+    # Allocate output matrices
+    shared_mat     = np.zeros((n, n), dtype=np.uint64)
+    hamming_mat    = np.zeros((n, n), dtype=np.float64)
+    jaccard_mat    = np.zeros((n, n), dtype=np.float64)
+    bray_mat       = np.zeros((n, n), dtype=np.float64)
+    relfreq_bray   = np.zeros((n, n), dtype=np.float64)
+    euclidean_mat  = np.zeros((n, n), dtype=np.float64)
+    relfreq_eucl   = np.zeros((n, n), dtype=np.float64)
+    hellinger_mat  = np.zeros((n, n), dtype=np.float64)
+    hell_eucl_mat  = np.zeros((n, n), dtype=np.float64)
+
+    for i in range(n):
+        a_km = specimens[i]['kmers']
+        a_ct = specimens[i]['counts'].astype(np.float64)
+        sa   = float(count_sums[i])
+        na   = int(kmer_counts[i])
+
+        for j in range(i + 1, n):
+            b_km = specimens[j]['kmers']
+            b_ct = specimens[j]['counts'].astype(np.float64)
+            sb   = float(count_sums[j])
+            nb   = int(kmer_counts[j])
+
+            idx_a, idx_b = shared_indices(a_km, b_km)
+            inter = len(idx_a)
+
+            ca_sh = a_ct[idx_a]
+            cb_sh = b_ct[idx_b]
+
+            # ── Presence metrics ──────────────────────────────────────────────
+
+            union   = na + nb - inter
+            jac     = (1.0 - inter / union) if union else 0.0
+            hamming = float(na + nb - 2 * inter)  # |A Δ B|
+
+            # ── Count metrics ─────────────────────────────────────────────────
+
+            # Bray-Curtis: 1 - 2*Σmin(a,b) / (Σa + Σb)
+            sum_min = np.minimum(ca_sh, cb_sh).sum()
+            denom_bc = sa + sb
+            bc = (1.0 - 2.0 * sum_min / denom_bc) if denom_bc else 0.0
+
+            # RelfreqBray: 1 - Σmin(a/sa, b/sb)  [only shared contribute]
+            if sa and sb:
+                rfb = 1.0 - np.minimum(ca_sh / sa, cb_sh / sb).sum()
+            else:
+                rfb = 0.0
+
+            # Euclidean: √(Σa² + Σb² - 2·Σ(a·b)_shared)
+            cross = (ca_sh * cb_sh).sum()
+            eucl_partial = sq_sums[i] + sq_sums[j] - 2.0 * cross
+            eucl = np.sqrt(max(eucl_partial, 0.0))
+
+            # RelfreqEuclidean: √(Σ(a/sa - b/sb)²)
+            # = √(Σa²/sa² + Σb²/sb² - 2·Σ(a·b)_shared/(sa·sb))
+            if sa and sb:
+                rf_cross = (ca_sh / sa * (cb_sh / sb)).sum()
+                rfe_partial = (sq_sums[i] / sa**2
+                               + sq_sums[j] / sb**2
+                               - 2.0 * rf_cross)
+                rfe = np.sqrt(max(rfe_partial, 0.0))
+            else:
+                rfe = 0.0
+
+            # Hellinger partial: Σ(√(a/sa) - √(b/sb))² over global universe
+            # = 2 - 2·Σ√(a·b)_shared / √(sa·sb)
+            if sa and sb:
+                bc_coeff = np.sqrt(ca_sh * cb_sh).sum() / np.sqrt(sa * sb)
+                hell_partial = max(2.0 - 2.0 * bc_coeff, 0.0)
+            else:
+                hell_partial = 0.0
+
+            sq2 = np.sqrt(2.0)
+            hell     = np.sqrt(hell_partial) / sq2
+            hell_euc = np.sqrt(hell_partial)
+
+            # ── Fill symmetric matrices ───────────────────────────────────────
+            for mat, val in [
+                (shared_mat,    inter),
+                (hamming_mat,   hamming),
+                (jaccard_mat,   jac),
+                (bray_mat,      bc),
+                (relfreq_bray,  rfb),
+                (euclidean_mat, eucl),
+                (relfreq_eucl,  rfe),
+                (hellinger_mat, hell),
+                (hell_eucl_mat, hell_euc),
+            ]:
+                mat[i, j] = val
+                mat[j, i] = val
+
+    return {
+        'shared_kmers':               shared_mat,
+        'hamming_dist':               hamming_mat,
+        'jaccard_dist':               jaccard_mat,
+        'bray_curtis_dist':           bray_mat,
+        'relfreq_bray_curtis_dist':   relfreq_bray,
+        'euclidean_dist':             euclidean_mat,
+        'relfreq_euclidean_dist':     relfreq_eucl,
+        'hellinger_dist':             hellinger_mat,
+        'hellinger_euclidean_dist':   hell_eucl_mat,
+    }
+
+
+# ── I/O ───────────────────────────────────────────────────────────────────────
+
+def write_csv(path: Path, labels: list[str], mat: np.ndarray, fmt: str) -> None:
+    with path.open('w') as fh:
+        fh.write('genome,' + ','.join(labels) + '\n')
+        for i, label in enumerate(labels):
+            row = ','.join(format(mat[i, j], fmt) for j in range(len(labels)))
+            fh.write(f'{label},{row}\n')
+    print(f'  → {path}', file=sys.stderr)
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('--ref-dir', default='reference_index',
+                    help='Directory with per-specimen .npz files (default: reference_index)')
+    ap.add_argument('--out-dir', default='reference_dist',
+                    help='Output directory for CSV files (default: reference_dist)')
+    args = ap.parse_args()
+
+    ref_dir = Path(args.ref_dir)
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(exist_ok=True)
+
+    npz_files = sorted(ref_dir.glob('*.npz'))
+    if not npz_files:
+        print(f'ERROR: no .npz files found in {ref_dir}', file=sys.stderr)
+        sys.exit(1)
+
+    print(f'Loading {len(npz_files)} specimen(s) from {ref_dir}/', file=sys.stderr)
+    specimens = []
+    for f in npz_files:
+        data = np.load(f)
+        specimens.append({
+            'name':   f.stem,
+            'kmers':  data['kmers'],
+            'counts': data['counts'],
+        })
+        print(f'  {f.stem}: {len(data["kmers"]):,} kmers', file=sys.stderr)
+
+    labels = [s['name'] for s in specimens]
+    n = len(labels)
+    print(f'\nComputing pairwise distances for {n} specimens…', file=sys.stderr)
+
+    matrices = pairwise_stats(specimens)
+
+    print(f'\nWriting CSVs to {out_dir}/', file=sys.stderr)
+    write_csv(out_dir / 'shared_kmers.csv',             labels, matrices['shared_kmers'],             'd')
+    write_csv(out_dir / 'hamming_dist.csv',             labels, matrices['hamming_dist'],             '.6f')
+    write_csv(out_dir / 'jaccard_dist.csv',             labels, matrices['jaccard_dist'],             '.6f')
+    write_csv(out_dir / 'bray_curtis_dist.csv',         labels, matrices['bray_curtis_dist'],         '.6f')
+    write_csv(out_dir / 'relfreq_bray_curtis_dist.csv', labels, matrices['relfreq_bray_curtis_dist'], '.6f')
+    write_csv(out_dir / 'euclidean_dist.csv',           labels, matrices['euclidean_dist'],           '.6f')
+    write_csv(out_dir / 'relfreq_euclidean_dist.csv',   labels, matrices['relfreq_euclidean_dist'],   '.6f')
+    write_csv(out_dir / 'hellinger_dist.csv',           labels, matrices['hellinger_dist'],           '.6f')
+    write_csv(out_dir / 'hellinger_euclidean_dist.csv', labels, matrices['hellinger_euclidean_dist'], '.6f')
+
+    print('\nDone.', file=sys.stderr)
+
+
+if __name__ == '__main__':
+    main()

benchmark/compare_all_dist.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""Compare all reference distance matrices against obikmer distance outputs.
+
+Reads from:
+  reference_dist/   — ground-truth matrices computed by build_reference_dist.py
+  obikmer_dist/     — matrices produced by `obikmer distance`
+
+Handles label reordering: both matrices are sorted by genome label before
+element-wise comparison, so column/row order differences are irrelevant.
+
+Output: stats/dist_comparison/summary.csv
+  comparison,max_abs,mean_abs,rmse,n_pairs,status
+"""
+import csv
+import sys
+from pathlib import Path
+
+import numpy as np
+
+
+# ── CSV loading ───────────────────────────────────────────────────────────────
+
+def load_matrix(path: Path) -> tuple[list[str], np.ndarray]:
+    """Load a distance-matrix CSV; return (sorted_labels, matrix_float64)."""
+    with path.open() as fh:
+        reader = csv.reader(fh)
+        header = next(reader)[1:]     # skip 'genome' column
+        raw: dict[str, list[float]] = {}
+        for row in reader:
+            raw[row[0]] = [float(x) for x in row[1:]]
+
+    label_to_col = {h: i for i, h in enumerate(header)}
+    labels = sorted(raw.keys())
+    n = len(labels)
+    mat = np.zeros((n, n), dtype=np.float64)
+    for i, ri in enumerate(labels):
+        for j, cj in enumerate(labels):
+            mat[i, j] = raw[ri][label_to_col[cj]]
+    return labels, mat
+
+
+# ── comparison ────────────────────────────────────────────────────────────────
+
+def compare(label: str,
+            ref_path: Path,
+            obi_path: Path,
+            tol: float = 1e-4) -> dict:
+    if not ref_path.exists():
+        return {'comparison': label, 'status': 'REF_MISSING',
+                'max_abs': '', 'mean_abs': '', 'rmse': '', 'n_pairs': ''}
+    if not obi_path.exists():
+        return {'comparison': label, 'status': 'OBI_MISSING',
+                'max_abs': '', 'mean_abs': '', 'rmse': '', 'n_pairs': ''}
+
+    ref_labels, ref_mat = load_matrix(ref_path)
+    obi_labels, obi_mat = load_matrix(obi_path)
+
+    if ref_labels != obi_labels:
+        only_ref = sorted(set(ref_labels) - set(obi_labels))
+        only_obi = sorted(set(obi_labels) - set(ref_labels))
+        print(f'  [{label}] label mismatch — '
+              f'only_ref={only_ref}  only_obi={only_obi}', file=sys.stderr)
+        return {'comparison': label, 'status': 'LABEL_MISMATCH',
+                'max_abs': '', 'mean_abs': '', 'rmse': '', 'n_pairs': ''}
+
+    n = len(ref_labels)
+    # Off-diagonal mask
+    mask = ~np.eye(n, dtype=bool)
+    diff = np.abs(ref_mat[mask] - obi_mat[mask])
+    n_pairs = diff.size
+
+    max_abs  = float(diff.max())
+    mean_abs = float(diff.mean())
+    rmse     = float(np.sqrt((diff ** 2).mean()))
+    status   = 'PASS' if max_abs <= tol else 'FAIL'
+
+    print(f'  [{label}] n={n_pairs}  '
+          f'max={max_abs:.3e}  mean={mean_abs:.3e}  rmse={rmse:.3e}  {status}',
+          file=sys.stderr)
+    return {
+        'comparison': label,
+        'max_abs':    f'{max_abs:.6e}',
+        'mean_abs':   f'{mean_abs:.6e}',
+        'rmse':       f'{rmse:.6e}',
+        'n_pairs':    str(n_pairs),
+        'status':     status,
+    }
+
+
+# ── comparison table ──────────────────────────────────────────────────────────
+
+# (label, ref_csv, obikmer_csv)
+# The reference jaccard/shared is presence-based, which should match both
+# presence/jaccard and count/jaccard (threshold=1).
+COMPARISONS = [
+    # ── presence index ────────────────────────────────────────────────────────
+    ('presence/jaccard_dist',
+     'reference_dist/jaccard_dist.csv',
+     'obikmer_dist/presence/jaccard_dist.csv'),
+
+    ('presence/jaccard_shared',
+     'reference_dist/shared_kmers.csv',
+     'obikmer_dist/presence/jaccard_shared.csv'),
+
+    ('presence/hamming_dist',
+     'reference_dist/hamming_dist.csv',
+     'obikmer_dist/presence/hamming_dist.csv'),
+
+    # ── count index (jaccard cross-check) ─────────────────────────────────────
+    ('count/jaccard_dist',
+     'reference_dist/jaccard_dist.csv',
+     'obikmer_dist/count/jaccard_dist.csv'),
+
+    ('count/jaccard_shared',
+     'reference_dist/shared_kmers.csv',
+     'obikmer_dist/count/jaccard_shared.csv'),
+
+    # ── count index (count-based metrics) ────────────────────────────────────
+    ('count/bray_curtis_dist',
+     'reference_dist/bray_curtis_dist.csv',
+     'obikmer_dist/count/bray_curtis_dist.csv'),
+
+    ('count/relfreq_bray_curtis_dist',
+     'reference_dist/relfreq_bray_curtis_dist.csv',
+     'obikmer_dist/count/relfreq_bray_curtis_dist.csv'),
+
+    ('count/euclidean_dist',
+     'reference_dist/euclidean_dist.csv',
+     'obikmer_dist/count/euclidean_dist.csv'),
+
+    ('count/relfreq_euclidean_dist',
+     'reference_dist/relfreq_euclidean_dist.csv',
+     'obikmer_dist/count/relfreq_euclidean_dist.csv'),
+
+    ('count/hellinger_dist',
+     'reference_dist/hellinger_dist.csv',
+     'obikmer_dist/count/hellinger_dist.csv'),
+
+    ('count/hellinger_euclidean_dist',
+     'reference_dist/hellinger_euclidean_dist.csv',
+     'obikmer_dist/count/hellinger_euclidean_dist.csv'),
+]
+
+
+# ── main ─────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    import argparse
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('--tol', type=float, default=1e-4,
+                    help='Max abs diff threshold for PASS/FAIL (default 1e-4)')
+    ap.add_argument('--out', default='stats/dist_comparison/summary.csv',
+                    help='Output summary CSV path')
+    args = ap.parse_args()
+
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    print(f'Comparing {len(COMPARISONS)} matrix pairs…', file=sys.stderr)
+    rows = []
+    for label, ref, obi in COMPARISONS:
+        rows.append(compare(label, Path(ref), Path(obi), tol=args.tol))
+
+    fields = ['comparison', 'max_abs', 'mean_abs', 'rmse', 'n_pairs', 'status']
+    with out_path.open('w', newline='') as fh:
+        w = csv.DictWriter(fh, fieldnames=fields)
+        w.writeheader()
+        w.writerows(rows)
+
+    print(f'\n→ {out_path}', file=sys.stderr)
+
+    n_fail = sum(1 for r in rows if r.get('status') == 'FAIL')
+    n_pass = sum(1 for r in rows if r.get('status') == 'PASS')
+    print(f'Summary: {n_pass} PASS  {n_fail} FAIL  '
+          f'{len(rows) - n_pass - n_fail} SKIP', file=sys.stderr)
+    if n_fail:
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

benchmark/test_dist.csv

@@ -0,0 +1,21 @@
+genome,Candidozyma_auris--GCF_003013715.1_ASM301371v2,Acidobacterium_capsulatum--ATCC_51196,Bacillus_subtilis--168,Escherichia_coli--CFT073,Escherichia_coli--EDL933,Escherichia_coli--K-12_MG1655,Escherichia_coli--K-12_W3110,Klebsiella_pneumoniae--ATCC_13883,Klebsiella_pneumoniae--HS11286,Klebsiella_pneumoniae--MGH_78578,Opitutus_terrae--PB90-1,Proteus_mirabilis--HI4320,Saccharolobus_islandicus--M.16.4,Salmonella_enterica--AKU_12601,Salmonella_enterica--CT18,Salmonella_enterica--LT2,Salmonella_enterica--P125109,Shouchella_clausii--KSM-K16,Wolbachia_endosymbiont--GCF_000306885.1_ASM30688v1,Yersinia_ruckeri--YRB
+Candidozyma_auris--GCF_003013715.1_ASM301371v2,0.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000
+Acidobacterium_capsulatum--ATCC_51196,1.000000,0.000000,0.999981,0.999990,0.999989,0.999987,0.999987,0.999990,0.999988,0.999988,0.999994,0.999989,1.000000,0.999988,0.999987,0.999987,0.999988,0.999989,0.999991,0.999987
+Bacillus_subtilis--168,1.000000,0.999981,0.000000,0.999990,0.999989,0.999989,0.999989,0.999989,0.999988,0.999986,0.999995,0.999985,0.999999,0.999988,0.999987,0.999989,0.999988,0.999778,0.999993,0.999987
+Escherichia_coli--CFT073,1.000000,0.999990,0.999990,0.000000,0.825741,0.807495,0.807218,0.991156,0.996855,0.997849,0.999996,0.999633,1.000000,0.993885,0.996736,0.994148,0.993821,0.999991,0.999984,0.999291
+Escherichia_coli--EDL933,1.000000,0.999989,0.999989,0.825741,0.000000,0.735107,0.734775,0.996126,0.998058,0.997908,0.999997,0.999640,1.000000,0.993993,0.997126,0.994390,0.994059,0.999991,0.999986,0.999292
+Escherichia_coli--K-12_MG1655,1.000000,0.999987,0.999989,0.807495,0.735107,0.000000,0.382567,0.996190,0.997747,0.997455,0.999996,0.999604,1.000000,0.993444,0.996645,0.993773,0.993431,0.999989,0.999984,0.999174
+Escherichia_coli--K-12_W3110,1.000000,0.999987,0.999989,0.807218,0.734775,0.382567,0.000000,0.996220,0.997761,0.997467,0.999995,0.999604,1.000000,0.993445,0.996669,0.993769,0.993443,0.999990,0.999985,0.999165
+Klebsiella_pneumoniae--ATCC_13883,1.000000,0.999990,0.999989,0.991156,0.996126,0.996190,0.996220,0.000000,0.845220,0.840545,0.999997,0.999648,1.000000,0.996177,0.998128,0.996268,0.996052,0.999990,0.999987,0.999325
+Klebsiella_pneumoniae--HS11286,1.000000,0.999988,0.999988,0.996855,0.998058,0.997747,0.997761,0.845220,0.000000,0.906475,0.999996,0.999683,1.000000,0.997724,0.995697,0.997776,0.997769,0.999989,0.999979,0.999463
+Klebsiella_pneumoniae--MGH_78578,1.000000,0.999988,0.999986,0.997849,0.997908,0.997455,0.997467,0.840545,0.906475,0.000000,0.999996,0.999704,1.000000,0.997928,0.995054,0.997844,0.997868,0.999990,0.999980,0.999479
+Opitutus_terrae--PB90-1,1.000000,0.999994,0.999995,0.999996,0.999997,0.999996,0.999995,0.999997,0.999996,0.999996,0.000000,0.999997,0.999998,0.999996,0.999996,0.999996,0.999995,0.999997,0.999993,0.999996
+Proteus_mirabilis--HI4320,1.000000,0.999989,0.999985,0.999633,0.999640,0.999604,0.999604,0.999648,0.999683,0.999704,0.999997,0.000000,1.000000,0.999604,0.999699,0.999622,0.999613,0.999987,0.999983,0.999505
+Saccharolobus_islandicus--M.16.4,1.000000,1.000000,0.999999,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,0.999998,1.000000,0.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000,1.000000
+Salmonella_enterica--AKU_12601,1.000000,0.999988,0.999988,0.993885,0.993993,0.993444,0.993445,0.996177,0.997724,0.997928,0.999996,0.999604,1.000000,0.000000,0.869238,0.682277,0.663383,0.999990,0.999985,0.999260
+Salmonella_enterica--CT18,1.000000,0.999987,0.999987,0.996736,0.997126,0.996645,0.996669,0.998128,0.995697,0.995054,0.999996,0.999699,1.000000,0.869238,0.000000,0.890872,0.886148,0.999988,0.999976,0.999524
+Salmonella_enterica--LT2,1.000000,0.999987,0.999989,0.994148,0.994390,0.993773,0.993769,0.996268,0.997776,0.997844,0.999996,0.999622,1.000000,0.682277,0.890872,0.000000,0.622606,0.999989,0.999985,0.999296
+Salmonella_enterica--P125109,1.000000,0.999988,0.999988,0.993821,0.994059,0.993431,0.993443,0.996052,0.997769,0.997868,0.999995,0.999613,1.000000,0.663383,0.886148,0.622606,0.000000,0.999988,0.999983,0.999270
+Shouchella_clausii--KSM-K16,1.000000,0.999989,0.999778,0.999991,0.999991,0.999989,0.999990,0.999990,0.999989,0.999990,0.999997,0.999987,1.000000,0.999990,0.999988,0.999989,0.999988,0.000000,0.999991,0.999988
+Wolbachia_endosymbiont--GCF_000306885.1_ASM30688v1,1.000000,0.999991,0.999993,0.999984,0.999986,0.999984,0.999985,0.999987,0.999979,0.999980,0.999993,0.999983,1.000000,0.999985,0.999976,0.999985,0.999983,0.999991,0.000000,0.999983
+Yersinia_ruckeri--YRB,1.000000,0.999987,0.999987,0.999291,0.999292,0.999174,0.999165,0.999325,0.999463,0.999479,0.999996,0.999505,1.000000,0.999260,0.999524,0.999296,0.999270,0.999988,0.999983,0.000000

benchmark/test_nj.nwk

@@ -0,0 +1 @@
+(((((((((((Candidozyma_auris--GCF_003013715.1_ASM301371v2:0.5000001881725941,Saccharolobus_islandicus--M.16.4:0.4999993211600824):0.0000023411501775538747,Opitutus_terrae--PB90-1:0.499997075187947):0.0000029791191795691675,(Acidobacterium_capsulatum--ATCC_51196:0.49999227771334689,(Bacillus_subtilis--168:0.49988797935621456,Shouchella_clausii--KSM-K16:0.49988984146059159):0.0001037210285571577):0.0000023959836053522034):0.0000034093646568700288,Wolbachia_endosymbiont--GCF_000306885.1_ASM30688v1:0.4999920159222422):0.000199555100890203,Proteus_mirabilis--HI4320:0.49979129185300427):0.00010103619067070024,Yersinia_ruckeri--YRB:0.4996806650749249):0.0013719139155004,(Klebsiella_pneumoniae--HS11286:0.43798845051648258,(Klebsiella_pneumoniae--ATCC_13883:0.41780293826821265,Klebsiella_pneumoniae--MGH_78578:0.42274184870836559):0.017586732339732737):0.0604124197073832):0.0006482538063555254,(Salmonella_enterica--CT18:0.43952894448143017,(Salmonella_enterica--AKU_12601:0.3357977326267918,(Salmonella_enterica--LT2:0.31203395843666389,Salmonella_enterica--P125109:0.31057217324861216):0.025729515856701136):0.10292985918524672):0.05825411485542886):0.08937928015651564,Escherichia_coli--CFT073:0.40806501650701029):0.0410131211869626,Escherichia_coli--EDL933:0.3681464750911808):0.1755112579711463,Escherichia_coli--K-12_MG1655:0.19129818036662728,Escherichia_coli--K-12_W3110:0.19126872019906239);

benchmark/test_shared.csv

@@ -0,0 +1,21 @@
+genome,Candidozyma_auris--GCF_003013715.1_ASM301371v2,Acidobacterium_capsulatum--ATCC_51196,Bacillus_subtilis--168,Escherichia_coli--CFT073,Escherichia_coli--EDL933,Escherichia_coli--K-12_MG1655,Escherichia_coli--K-12_W3110,Klebsiella_pneumoniae--ATCC_13883,Klebsiella_pneumoniae--HS11286,Klebsiella_pneumoniae--MGH_78578,Opitutus_terrae--PB90-1,Proteus_mirabilis--HI4320,Saccharolobus_islandicus--M.16.4,Salmonella_enterica--AKU_12601,Salmonella_enterica--CT18,Salmonella_enterica--LT2,Salmonella_enterica--P125109,Shouchella_clausii--KSM-K16,Wolbachia_endosymbiont--GCF_000306885.1_ASM30688v1,Yersinia_ruckeri--YRB
+Candidozyma_auris--GCF_003013715.1_ASM301371v2,0,0,0,0,0,0,0,0,0,0,0,0,8,0,1,0,0,0,0,3
+Acidobacterium_capsulatum--ATCC_51196,0,0,203,119,128,141,140,116,109,111,78,112,0,136,109,147,134,117,55,129
+Bacillus_subtilis--168,0,203,0,124,132,128,123,133,109,130,66,158,6,131,112,124,135,2393,46,124
+Escherichia_coli--CFT073,0,119,124,0,1966777,1998059,1999094,117743,32029,22312,63,4225,0,74946,31918,73311,76585,113,128,7854
+Escherichia_coli--EDL933,0,128,132,1966777,0,2627885,2628700,52488,20134,22064,48,4202,0,74655,28602,71244,74665,112,108,7963
+Escherichia_coli--K-12_MG1655,0,141,128,1998059,2627885,0,4452541,48302,21382,24602,47,4277,0,75729,30449,73622,76778,119,111,8566
+Escherichia_coli--K-12_W3110,0,140,123,1999094,2628700,4452541,0,47894,21226,24470,68,4278,0,75658,30207,73614,76583,112,108,8660
+Klebsiella_pneumoniae--ATCC_13883,0,116,133,117743,52488,48302,47894,0,1416091,1477759,42,4172,0,48296,18988,48144,50416,120,106,7712
+Klebsiella_pneumoniae--HS11286,0,109,109,32029,20134,21382,21226,1416091,0,644063,42,2738,0,21498,29758,21606,21376,99,102,4417
+Klebsiella_pneumoniae--MGH_78578,0,111,130,22312,22064,24602,24470,1477759,644063,0,42,2614,0,19948,35067,21330,20813,97,102,4374
+Opitutus_terrae--PB90-1,0,78,66,63,48,47,68,42,42,42,0,43,18,57,42,53,66,39,58,43
+Proteus_mirabilis--HI4320,0,112,158,4225,4202,4277,4278,4172,2738,2614,43,0,0,4254,2481,4166,4215,131,103,4704
+Saccharolobus_islandicus--M.16.4,8,0,6,0,0,0,0,0,0,0,18,0,0,0,0,0,0,0,0,0
+Salmonella_enterica--AKU_12601,0,136,131,74946,74655,75729,75658,48296,21498,19948,57,4254,0,0,1047731,2857146,2951421,117,108,7643
+Salmonella_enterica--CT18,1,109,112,31918,28602,30449,30207,18988,29758,35067,42,2481,0,1047731,0,917948,940297,106,106,3716
+Salmonella_enterica--LT2,0,147,124,73311,71244,73622,73614,48144,21606,21330,53,4166,0,2857146,917948,0,3284800,122,108,7460
+Salmonella_enterica--P125109,0,134,135,76585,74665,76778,76583,50416,21376,20813,66,4215,0,2951421,940297,3284800,0,134,124,7645
+Shouchella_clausii--KSM-K16,0,117,2393,113,112,119,112,120,99,97,39,131,0,117,106,122,134,0,58,124
+Wolbachia_endosymbiont--GCF_000306885.1_ASM30688v1,0,55,46,128,108,111,108,106,102,102,58,103,0,108,106,108,124,58,0,96
+Yersinia_ruckeri--YRB,3,129,124,7854,7963,8566,8660,7712,4417,4374,43,4704,0,7643,3716,7460,7645,124,96,0

docmd/architecture/numa_partition_runner.md

@@ -162,14 +162,158 @@ A single `PartitionRunner` instance can be built once per command invocation
 and reused across multiple `run()` calls (e.g. `merge` runs
 `merge_partitions` then `pack_matrices`).
 
+## Known issue: CPU-only activation signal stalls on I/O-bound stages
+
+Observed on a real `filter` run (109 genomes, 256 partitions, 8×24-core NUMA):
+`rebuild` (CPU-bound — k-mer construction) scales cleanly from 9 to 43 active
+workers as `CpuSample::do_i_activate` (`obisys::lib.rs`) sees efficiency climb.
+`pack_matrices` (I/O-bound — reopens and recomposes per-genome column files
+into `.pbmx`/`.pcmx`) activates one extra worker then flatlines at 10/192 for
+the rest of the stage, even though 256 partitions keep completing over several
+minutes. This matches the documented intent (§ Adaptive mechanism — "avoids
+over-provisioning ... I/O-bound ... workloads") but conflates two different
+things: *"CPU is not the bottleneck"* and *"more workers would not help"*. On
+storage with real queue depth (NVMe, RAID, parallel FS) the second stage could
+still benefit from more concurrent workers even with flat CPU usage — a signal
+the current mechanism cannot see.
+
+A one-off artefact was also found in the same log: right after a stage
+transition, `do_i_activate` produced a physically impossible spike (efficiency
+~94 cores on a 192-core box) because it has no minimum-window guard — unlike
+its sibling `cpu_efficiency`, which returns `0.0` if `wall < 0.1s`
+(`obisys::lib.rs:260`). `do_i_activate` unconditionally overwrites
+`self.wall`/`self.user_secs`/`self.sys_secs` even when the elapsed window is
+too short to be meaningful, so a burst of rapid completions right after
+activating a worker can divide a real CPU delta by a near-zero wall delta.
+
+### Implemented: I/O signal + shared debounce guard
+
+`IoSample` (`obisys::lib.rs`, alongside `CpuSample`) is fed by
+`read_bytes`/`write_bytes` from `/proc/self/io` on Linux (actual bytes
+submitted to the block layer — not `rchar`/`wchar`, which also count
+page-cache hits, and not `ru_inblock`/`ru_oublock`, unreliable on macOS), with
+a `proc_pid_rusage(RUSAGE_INFO_V4)` fallback on macOS
+(`ri_diskio_bytesread`/`ri_diskio_byteswritten`, FFI only via `libc`, no new
+dependency — same pattern as the existing `getrusage` bindings). Any other
+target degrades gracefully to a signal that never triggers (falls back to
+CPU-only activation), same pattern as `cgroup_v2_available`.
+
+`maybe_activate` (`numa.rs`) activates a worker if *either* signal still shows
+headroom, making `PartitionRunner` adapt to whichever resource is actually the
+bottleneck without per-call configuration. Both samplers are called
+unconditionally — no `||` short-circuit — so neither window starves behind
+whichever signal fires first:
+
+```rust
+let cpu_threshold = CPU_SPAWN_THRESHOLD * activation.last_step() as f64;
+let cpu_wants_more = cpu_sample.do_i_activate(cpu_threshold);
+let io_wants_more  = io_sample.do_i_activate(IO_SPAWN_THRESHOLD);
+if cpu_wants_more || io_wants_more {
+    activation.grow(GROWTH_DIVISOR, n_total);
+}
+```
+
+The CPU threshold is *not* the flat absolute delta it started as: it scales
+with `activation.last_step()` — the number of workers activated in the last
+growth step, tracked by `NodeActivation` (`numa.rs`) and updated every time
+`grow()` actually grows something. Growing by 8 workers should add ~8 cores of
+efficiency if the workload is truly CPU-bound; requiring only
+`CPU_SPAWN_THRESHOLD` (20 %) of that expected gain confirms the growth was
+useful without demanding perfect linear scaling. Scaling by the *last step's
+size* rather than the cumulative total keeps the bar equally meaningful
+whether it's the 2nd growth step or the 20th — a flat absolute threshold
+(0.2 core) is a strong signal at 8 active workers but pure noise at 150; a
+threshold scaled by the *cumulative* total instead (considered and rejected)
+would have made the bar essentially impossible to clear late in the ramp,
+strangling exactly the CPU-bound saturation the mechanism exists to allow.
+
+Unlike the CPU signal (an absolute delta in cores — a bounded, portable unit),
+raw I/O throughput has no natural scale across devices, so `IoSample` uses a
+**relative** growth threshold instead of an absolute one:
+
+```rust
+pub fn do_i_activate(&mut self, threshold: f64) -> bool {
+    let elapsed = self.wall.elapsed().as_secs_f64();
+    if elapsed < 0.1 { return false; }        // state untouched — window keeps accumulating
+
+    let n = Self::read_bytes();
+    let rate = n.saturating_sub(self.bytes) as f64 / elapsed;
+    let activate = if self.previous_rate == 0.0 {
+        rate > 0.0                            // bootstrap: any measured throughput is signal
+    } else {
+        (rate - self.previous_rate) / self.previous_rate >= threshold
+    };
+
+    self.bytes = n;
+    self.wall  = Instant::now();              // reset only on a real sample
+    activate
+}
+```
+
+The `elapsed < 0.1s → return false without mutating state` guard was also
+back-ported into `CpuSample::do_i_activate` (previously missing — source of
+the ~94-core artefact above) — one fix for both problems, and it removes the
+need for any arbitrary I/O-rate floor: a short/noisy window is rejected
+outright rather than papered over with a hardware-dependent constant.
+
+Both spawn thresholds (`CPU_SPAWN_THRESHOLD`, `IO_SPAWN_THRESHOLD`, module-level
+`const` in `numa.rs`, both `0.2`) are a starting point, not a derived value:
+`0.2` (20 % relative growth) for `IoSample` was chosen to match the CPU
+threshold's *implicit* relative sensitivity (in the observed log, an 8→9
+worker step raised efficiency by ~12 %) — but I/O throughput is lumpier than
+CPU time (buffered writes flush in bursts), so it needs empirical validation
+against a real `pack` run before being considered final.
+
+## Known issue: ramp-up too slow, and confused with node count
+
+The original design started `n_nodes` workers (one per node) and grew one
+worker at a time. On a real `filter` run this took ~10 minutes to climb from
+9 to ~40 active workers even on the CPU-bound `rebuild` stage — most of a
+35-minute stage spent under-provisioned while waiting for evidence to
+accumulate one worker at a time. There is no scale-down mechanism (`n_active`
+only grows), so the original caution was deliberate — but a quarter of
+available cores is still far from saturation, and the real risk zone (over-provisioning
+a memory-bandwidth-bound stage) only shows up much later in the ramp, near
+full occupancy — not at 25 %.
+
+The fix decouples ramp speed from node *count*: both the initial size and the
+growth step are a fraction of `workers_per_node` (node *size*), applied
+identically on every node. A single-NUMA-node (UMA) machine ramps exactly as
+fast as an 8-node one — growing by `n_nodes` per step, as first considered,
+would have degenerated to "grow by 1" on UMA, reproducing the original
+problem for exactly the machines that need the fix most.
+
+```rust
+// NodeActivation::grow — called both at startup (activate_initial) and on
+// every CPU/IO-triggered growth step, with a different divisor each time.
+let wanted = (self.caps[idx] / divisor).max(1);   // INITIAL_DIVISOR=4 at startup, GROWTH_DIVISOR=8 per step
+let room   = self.caps[idx].saturating_sub(self.active[idx]);
+let grow   = wanted.min(room).min(n_total.saturating_sub(self.total));
+```
+
+This also fixed a latent correctness gap: the original single shared
+`activate_tx`/`activate_rx` pair had *no* per-node addressing — sending one
+activation signal woke up whichever dormant worker (from any node) happened
+to win the race on that channel. `crossbeam_channel` gives no fairness
+guarantee across competing receivers, so "round-robin across nodes" was an
+assumption the code never actually enforced. `PartitionRunner::run` now opens
+one activation channel per node (`activate_txs`/`activate_rxs`, one pair per
+`NodeConfig`); `NodeActivation` (`numa.rs`) tracks how many of each node's
+dormant workers have been woken and grows every node by the same amount per
+step, capped by that node's remaining dormant workers and by the run's total
+budget (`n_total`) — balance across nodes is now guaranteed by construction,
+not incidental to channel implementation details.
+
 ## Open questions
 
 - **Error handling**: `run` currently returns the first error; remaining errors
   are dropped.  A `Vec<E>` return would give complete diagnostics.
 
-- **`workers_per_node` tuning**: currently `(cpus / 8).max(3).min(8)`, calibrated
+- **`INITIAL_DIVISOR` / `GROWTH_DIVISOR` tuning**: currently `4` and `8`
-  for merge on BeeGFS.  I/O-bound commands (`dump`, `select`) may benefit from
+  (start at 1/4 of a node's cores, grow by 1/8 per step), chosen to fix an
-  a higher value.  A per-call override could be added to the API.
+  observed too-slow ramp — not yet validated against a real `pack` (I/O-bound)
+  run, where over-provisioning risk is different from the CPU-bound `rebuild`
+  case this was tuned against.
 
 - **`on_done` ordering**: the runner serialises calls to `on_done` via an
   internal `Arc<Mutex<C>>`.  `Send` is required (the Arc clone crosses thread

docmd/architecture/query.md

@@ -16,27 +16,43 @@ Given a set of query sequences, determine for each sequence how many of its k-me
 
 ## Algorithm
 
-The query follows the same superkmer-based partitioning strategy used at indexing time.
+The query follows the same superkmer-based partitioning strategy used at indexing time. Everything below happens inside `process_chunk` (`query.rs`); there is no separate per-stage function, but the internal data flow is staged: k-mer-level dereplication, a two-part MPHF/column-major matrix lookup (`obikpartitionner::query_partition_with`), and a sparse Findere pass, each producing sparse intermediate structures rather than one dense allocation for the whole chunk.
 
 ```
-for each chunk of sequences (parallel workers via obipipeline):
+for each chunk of sequences (parallel workers via obipipeline, one call to process_chunk):
-    build QueryBatch: decompose all sequences into s-mers via superkmers, deduplicate
+    build QueryBatch (QueryBatch::from_records):
-    allocate seq_results[seq_idx][smer_pos] = None  ← per-sequence s-mer result vectors
+        decompose all sequences into superkmers (SuperKmerIter) — construction only,
-    split superkmers by partition via minimiser hash
+        not the dedup key
+        deduplicate at k-mer granularity, split by partition in the same pass:
+            by_partition: Vec<HashMap<CanonicalKmer, Vec<KmerDesc>>>   ← KmerDesc = (seq_idx, pos)
+    allocate SmerIndex (SmerIndex::new): in_index: Vec<bool>, sized total_smers —
+        NOT multiplied by n_genomes
+    allocate by_genome: Vec<Vec<(seq_idx, pos, value)>>, one empty Vec per genome —
+        stays empty (zero cost) for every genome this chunk never matches
     for each partition p:
-        query_partition(p, superkmers_routed_to_p)
+        query_partition_with(p, kmers_for_p, on_event):
-            → load QueryLayer(s) for p
+            stage 1 (MPHF-only): for each unique k-mer, try each layer's MphfLayer::find
-            → for each s-mer in each superkmer: MphfLayer::find(smer)
+                in turn, stop at the first hit; bucket confirmed hits by (layer, slot);
-        fill seq_results[seq_idx][kmer_offset + j] from partition results
+                emit QueryHit::Found(descs) once per hit k-mer
-    for each sequence:
+            stage 2 (column-major fetch): for each layer with ≥1 hit, for each genome
-        apply_findere(seq_results[seq_idx], effective_z)  ← per full sequence
+                column g in 0..layer.n_cols(): scan that layer's bucketed slots, look up
-        accumulate confirmed k-mer results into acc and cov
+                col_value(g, slot); emit QueryHit::Value(descs, g, value) on nonzero
-    emit annotated sequences
+        on_event dispatches: Found → SmerIndex::mark_found for every desc;
+                              Value → push (seq_idx, pos, value) into by_genome[g]
+    for each genome g with ≥1 hit (sparse_findere_for_genome):
+        sort by_genome[g] by (seq_idx, pos); detect maximal runs of consecutive pos
+        within one seq_idx; monotone-deque window-minimum scoped to each run →
+        confirmed_by_genome[g]: Vec<(seq_idx, pos_out, value)>
+    accumulate genome_totals per sequence from confirmed_by_genome (per genome, direct)
+    accumulate kmer_count / kmer_missing per (sequence, output position), O(1) each,
+        using only the confirmed-any bitmap and SmerIndex — independent of n_genomes
+    if --detail: densify confirmed_by_genome into per-(seq, genome) coverage arrays
+    emit annotated sequences (emit_batch)
 ```
 
-Superkmers that appear more than once in the batch (same sequence or across sequences) are deduplicated: each unique `RoutableSuperKmer` is queried once per partition, and the result is broadcast to every `SKDesc` entry that references it.
+Superkmers that appear more than once in the batch (same sequence or across sequences), or different superkmers that happen to share a k-mer (read overlaps, repeats, a SNP splitting an otherwise-identical run), are deduplicated at k-mer granularity: each unique `CanonicalKmer` triggers at most one MPHF lookup and, on hit, one matrix fetch, broadcast to every `KmerDesc` occurrence referencing it.
 
-**Findere requires full-sequence aggregation.** `apply_findere` is applied once per sequence on the complete s-mer result vector, after all partitions have contributed. Applying it per superkmer would produce false negatives at superkmer boundaries, where the z-window spans two superkmers.
+**Findere requires full-sequence aggregation.** The sliding window (now per-run, not per-sequence — see [Findere z-window filter](#findere-z-window-filter)) only ever runs after all partitions have contributed their hits to `by_genome`. Applying it per superkmer would produce false negatives at superkmer boundaries, where the z-window spans two superkmers.
 
 Batches are processed in parallel via `obipipeline` workers; the `--threads` flag controls the number of worker threads.
 
@@ -44,25 +60,46 @@ Batches are processed in parallel via `obipipeline` workers; the `--threads` fla
 
 ## Findere z-window filter
 
-For approximate index modes, the index physically stores s-mers of size `s = k_user − z + 1`. At query time, `set_k(s)` is in effect, so queries naturally produce s-mer results. `apply_findere` then aggregates z consecutive s-mer results into one k_user-mer answer:
+For approximate index modes, the index physically stores s-mers of size `s = k_user − z + 1`; `idx.kmer_size()` (bound to `k` in `process_chunk`) is this physically-indexed s-mer size, so decomposing the query at `k` naturally produces s-mer results.
 
-```rust
+The z-window aggregation is **sparse**, per genome, implemented in `sparse_findere_for_genome` (`query.rs`) — a run-detection pass followed by a monotone-deque sliding-window minimum scoped to each run, not a dense scan over every s-mer position of every sequence:
-fn apply_findere(
+
-    results: &[Option<Box<[u32]>>],  // N s-mer results
+```
-    z: usize,
+sparse_findere_for_genome(hits, z, presence, threshold):
-    n_genomes: usize,
+    // hits: raw (seq_idx, pos_smer, value) triples for this genome, as delivered
-) -> Vec<Option<Box<[u32]>>>         // N − z + 1 k_user-mer results
+    // by query_partition_with's QueryHit::Value — only ever nonzero entries;
+    // a position with no hit for this genome simply has no entry at all.
+    sort hits by (seq_idx, pos_smer)
+
+    for each maximal run of consecutive pos_smer values within the same seq_idx:
+        dq: VecDeque<(run-relative index, value)>
+        for k, (_, pos, value) in enumerate(run):
+            maintain dq monotone non-decreasing (pop back while back.value >= value)
+            push (k, value)
+            evict dq entries with run-relative index <= k - z
+            if k + 1 >= z:
+                win_min = dq.front().value
+                if win_min > 0:
+                    pos_out = pos + 1 - z
+                    confirmed.push((seq_idx, pos_out, adjust(win_min)))
+    return confirmed
 ```
 
-Input length N (s-mers), output length N − z + 1 (k_user-mers).
+A window can only be confirmed (`win_min > 0`) when all `z` s-mers in it are present *and* nonzero for this genome — which, by construction, can only happen strictly inside one contiguous run of hits (any gap — an absent or zero-valued s-mer — forces `win_min = 0` for every window spanning it, exactly matching the old dense scan's "not in index counts as 0" rule, just never materialising the zero). The deque logic is otherwise identical to the pre-sparsification version; it's scoped to run-relative indices instead of the whole sequence.
 
-For each genome g independently, a sliding window of size z scans the input. Output position i is confirmed for genome g iff all z values `results[i..i+z][g]` are nonzero (`None` counts as zero for all genomes). The scan is O(n) per genome.
+This runs once per genome that has at least one hit in the chunk (`process_chunk` iterates `by_genome`, one `Vec<(seq_idx, pos_smer, value)>` per genome, built from `QueryHit::Value` during the partition loop — genomes with zero hits in this chunk have an empty `Vec` and cost nothing beyond the iteration itself). Total work is `O(hits log hits)` per genome (the sort) rather than `O(n_smers)` per genome regardless of hit count — a genuine complexity win on top of the memory one, for the common case where most `(chunk, genome)` pairs have no or few hits.
 
-Output values come from `results[i]` (leftmost s-mer of each window); genomes not confirmed are zeroed. If all genomes are zero, the position is returned as `None`.
+Output position `pos_out` is confirmed for genome `g` iff its run produced a nonzero `win_min` — equivalent to "all `z` consecutive s-mer values in the window are nonzero for `g`", same semantics as before.
 
-**Short sequences**: when the s-mer count is less than z, no complete window can form — `apply_findere` returns an empty vector. K-mers from sequences shorter than k_user are not emitted.
+**The value reported per confirmed position is the window minimum, not the leftmost s-mer's raw value** — unchanged from the dense version. For presence indexes (0/1 values) this is equivalent to a logical AND either way. For count indexes it is not: the accumulated count for genome `g` at position `pos_out` is the minimum across the window, the weakest link — not the leftmost s-mer's own count. The presence/count adjustment (`u32::from(win_min >= threshold)` vs. raw `win_min`) is applied once, inside `sparse_findere_for_genome`, rather than later during accumulation.
 
-**Exact indexes**: `z = 1`, `apply_findere` is a passthrough (output length = input length).
+**`kmer_missing` bookkeeping is independent of the per-genome sparse structures**, by design (see roadmap point 9): a lightweight dense `SmerIndex` (`in_index: Vec<bool>`, sized `total_smers` — **not** multiplied by `n_genomes`) is populated from `QueryHit::Found` during the partition loop, one entry per hit k-mer regardless of which genome(s) it matched. A position with no genome confirmed counts as `kmer_missing` iff the leftmost s-mer of that window is absent from `SmerIndex` entirely (see [`kmer_missing` semantics](#kmer_missing-semantics)).
+
+**Coverage (`--detail`)** is built by re-scanning each genome's confirmed-hit list (already computed, no extra pass over raw data) and densifying into the `[u32; n_kmers_out]` arrays the JSON output format requires — but only when `--detail` is actually requested; the sparse structures cost nothing extra when it isn't.
+
+**Short sequences**: when a sequence's s-mer count is less than `z`, its run(s) — if any hits exist at all — can never reach length `z`, so no window is ever confirmed for it; no k_user-mer is emitted, same outcome as the dense version's `n_kmers_out == 0` early-skip, reached here as a natural consequence rather than a separate check.
+
+**Exact indexes**: `z = 1`, every single-hit "run" of length 1 immediately satisfies `k + 1 >= z`, so every hit is its own confirmed window with `win_min` equal to its own value — a passthrough, as before.
 
 ### Effective z at query time
 
@@ -85,14 +122,17 @@ The `-z` CLI option overrides the index metadata value. A higher z increases str
 
 ### `QueryLayer` variant selection
 
-`QueryLayer::open` in `query_layer.rs` selects the data matrix to pair with `MphfLayer`:
+`QueryLayer::open` (`obikpartitionner/src/query_layer.rs:28-45`) only ever returns two variants — `Presence` or `Count`, checked in this order:
 
-| Condition | Variant | Data returned per k-mer |
+| Order | Condition | Variant | Data returned per k-mer |
-|---|---|---|
+|---|---|---|---|
-| `with_counts=true` and `counts/` exists | `Count` | raw count per genome |
+| 1 | `with_counts=true` and `counts/` exists | `Count` | raw count per genome |
-| `presence/` exists | `Presence` | 0/1 per genome (bit matrix) |
+| 2 | (else) `presence/` exists, or `counts/` doesn't exist at all | `Presence` | see below |
-| only `counts/` exists | `Count` | counts used as-is |
+| 3 | (else — `counts/` exists, `presence/` doesn't, `with_counts=false`) | `Count` | counts used as-is |
-| neither exists | `SetOnly` | 1 for every genome |
+
+There is no `QueryLayer::SetOnly` variant. The "no on-disk matrix at all" case is handled one level down: `Presence` wraps `PersistentBitMatrix`, whose own `open()` (`obicompactvec/src/bitmatrix.rs:260-288`) auto-detects among **three** internal representations — `Packed` (`presence/matrix.pbmx`), `Columnar` (`presence/meta.json`), or `Implicit { n_rows, n_cols }` when neither file exists (built from `layer_meta.json`, `fill_row` returning all-`1`s without touching disk). This is where "1 for every genome" actually happens — not at the `QueryLayer` level.
+
+**Worth double-checking, not confirmed as a bug**: `PersistentBitMatrix::open`'s `Implicit` branch constructs `Implicit { n_rows: meta.n, n_cols: 1 }` — `n_cols` is hardcoded to `1`, not to the layer's actual `n_genomes`. `fill_row` for `Implicit` only writes `buf[..1]`, leaving the rest of a longer `n_genomes`-sized buffer untouched (zeroed by the caller beforehand). If this path is ever reached for a layer covering more than one genome, only genome index 0 would read as present. Whether that's reachable in practice (layers might always be single-genome when they fall back to `Implicit`) wasn't verified here — flagging for follow-up, not fixing.
 
 ---
 
@@ -123,7 +163,7 @@ Coverage reflects confirmed k_user-mers only. The vectors are emitted in the JSO
 
 ## `kmer_missing` semantics
 
-`kmer_missing` counts k_user-mer positions where the first s-mer (`seq_results[seq_idx][pos]`) is `None` — i.e. absent from the index entirely. K-mers where the z-window fails because a later s-mer is absent or zero are not counted as missing (the first s-mer being present is used as proxy for index membership).
+`kmer_missing` counts k_user-mer positions where the leftmost s-mer of the window (`smer_index.is_in_index(seq_idx, pos)`, `SmerIndex`) is `false` — i.e. absent from the index entirely. K-mers where the z-window fails because a later s-mer is absent or zero (but the leftmost one is present) are not counted as missing — the leftmost s-mer being present is used as proxy for index membership.
 
 ---
 
@@ -152,8 +192,8 @@ Genome keys follow the iteration order of `meta.genomes`.
 | Key | Type | Condition | Semantics |
 |---|---|---|---|
 | `kmer_count` | int | always | k-mers confirmed (post-Findere) with at least one genome match |
-| `kmer_missing` | int | `--count-missing` | k-mers absent from the index entirely (pre-Findere None) |
+| `kmer_missing` | int | `--count-missing` | k-mers absent from the index entirely (leftmost s-mer of the window not found) |
-| `kmer_strict_matches` | object | always | per-genome accumulated value (label → count or 0/1) |
+| `kmer_strict_matches` | object | always | per-genome accumulated value, non-zero entries only (label → count or 0/1) |
 | `coverage` | object | `--detail` | per-genome array of per-position contributions (label → [u32]) |
 
 `kmer_count + kmer_missing` ≤ total k_user-mers in the sequence. The gap corresponds to k_user-mers whose z-window was not fully confirmed (at least one s-mer absent or zero for all genomes) but whose first s-mer was present in the index.
@@ -165,7 +205,7 @@ Genome keys follow the iteration order of `meta.genomes`.
 ```
 obikmer query <index> [--detail] [--mismatch] [--count-missing]
               [--force-presence] [--presence-threshold <n>]
-              [-z <z>] [-T <threads>]
+              [-z <z>] [-T <threads>] [--chunk-size <MiB>]
               <query.fa> [<query2.fa> ...]
 ```
 
@@ -177,6 +217,7 @@ obikmer query <index> [--detail] [--mismatch] [--count-missing]
 | `--force-presence` | off | Report 0/1 per genome regardless of index counts |
 | `--presence-threshold` | 1 | Minimum count to declare genome present |
 | `-T` / `--threads` | all CPUs | Worker threads |
+| `--chunk-size` | auto (from available RAM and thread count) | I/O chunk size in MiB — see [Future work, point 3](#throughput--parallelism--identified-potential-not-yet-implemented) for why the auto-sizing formula currently under-estimates memory on indexes with many genomes |
 
 `--mismatch` is accepted but currently ignored with a warning on stderr.
 
@@ -187,3 +228,179 @@ obikmer query <index> [--detail] [--mismatch] [--count-missing]
 - **`--mismatch`**: 1-mismatch approximate matching — generate `3·k` single-substitution variants per k-mer, look each up independently.
 - **Read classification** (`--classify`): assign each read to the genome with the highest match score.
 - **Whitelist / blacklist filtering**: threshold-based accept/reject on per-genome match scores.
+
+### Throughput & parallelism — identified potential (not yet implemented)
+
+Observed on a 192-core (8×24 NUMA) machine: `query` uses ~10 cores or fewer, and the default chunk size gets the process OOM-killed. Root causes and candidate fixes, in dependency order:
+
+**1. Single-threaded I/O source (main core-utilization bottleneck).**
+`run()` builds `all_chunks` via `paths.into_iter().flat_map(read_sequence_chunks_sized(...))` and passes it directly as the `input` iterator to `pipe.apply()`. In `obipipeline::Pipe::apply` (`scheduler.rs`), `input.next()` is called exclusively from the dedicated source thread — so file opening, decompression, and FASTA/FASTQ chunk-boundary parsing for *all* input files run serially in one thread, regardless of `--threads`. Compare with `steps::scatter` (used by `index`) and `cmd/superkmer.rs`: there, file opening + streaming is itself a `Flat` pipeline stage (`||?`), executed across the `n_workers` pool, with `obipipeline::throttle(paths, max_open)` bounding concurrently-open files in the source thread. That pattern parallelises I/O across files (and NUMA nodes); `query.rs` cannot.
+Fix direction: restructure `query`'s pipe with an initial `Flat` stage analogous to `scatter`'s, opening/chunking files across workers instead of in `flat_map`.
+
+**2. Gzip decompression is inherently single-threaded per file.**
+`niffler`/`flate2` (used by `xopen`) do standard DEFLATE, which has no parallel-decodable structure for an arbitrary stream. Fix (1) parallelises *across* files but not *within* one large gzip file. Parking a possible fix (`rapidgzip-rs`) is tracked in [chunkreader.md](../implementation/chunkreader.md#future-work--parallel-gzip-decompression-in-xopen).
+
+**3. Chunk-size memory formula ignores `n_genomes`.**
+`chunk_bytes = available_memory_bytes() / (n_workers * 16)` (`query.rs:407-414`) assumes a fixed ~8–16× overhead per raw input byte. But `KmerResults::new` (`query.rs:165-179`) allocates `data: Vec<u32>` sized `total_kmers_in_chunk × n_genomes` — dense, **for every k-mer position in the chunk, hit or not** — plus `win_min` and (with `--detail`) `cov`, same scaling. Real per-chunk memory is `O(n_genomes)`, not constant; the formula doesn't know `n_genomes` at all. This is the direct cause of the OOM kill on indexes with many reference genomes.
+
+**4. MPHF lookup and matrix-row fetch are fused, not staged.**
+`QueryLayer::find_into` (`obikpartitionner/src/query_layer.rs:48-67`) does the MPHF `find` *and* the `fill_row` matrix read in one call per k-mer, inside a single-threaded loop (`query_partition_with`). There is no separation between "is this k-mer indexed" (cheap, `O(1)`, independent of `n_genomes`) and "what are its per-genome values" (the expensive, `n_genomes`-scaling part).
+
+**5. Dereplication should happen at k-mer granularity, directly — not via an intermediate superkmer-level dedup.**
+`QueryBatch::from_records` currently dereplicates at the *superkmer* level (`HashMap<RoutableSuperKmer, Vec<SKDesc>>`, `query.rs:112`). This misses redundancy between k-mers shared by *different* superkmers (read overlaps, repeats, a SNP splitting an otherwise-identical run). Superkmer *construction* (`SuperKmerIter`) stays mandatory — it is the mechanism that computes minimizers/partition routing, not an optional dedup layer — but the dedup structure built on top of it should key directly on `CanonicalKmer`, in the same pass: `HashMap<CanonicalKmer, Vec<(seq_idx, pos)>>`. This also means the MPHF `find` itself runs once per **distinct** k-mer instead of once per occurrence — a win independent of the matrix-fetch cost below.
+
+**6. Stage 1 output: bucket confirmed hits by layer, keyed by MPHF slot.**
+For each unique canonical k-mer, MPHF lookup across a partition's layers stops at the first match (`query_partition_with:105-111`) — a k-mer belongs to at most one layer. So stage 1's output can be reshaped directly into:
+```
+HashMap<layer_idx, HashMap<slot, Vec<(seq_idx, pos)>>>
+```
+replacing the `CanonicalKmer` key by the resolved `slot` (compact integer, and exactly what stage 2 needs to address the matrix). K-mers matching no layer simply have no entry here (they still count toward `in_index`/`kmer_missing` bookkeeping, which stays `O(1)` per position, independent of `n_genomes`).
+
+**7. Partition-level parallelism is currently absent — and a NUMA-aware mechanism for exactly this already exists, unused, in `obikindex`.**
+`process_chunk`'s partition loop (`query.rs:250-278`, `for (part_idx, part_sks) in by_part.iter().enumerate()`) processes every partition of a chunk sequentially on the single worker thread that owns that chunk. This is a parallelism axis on its own, independent of the column question below.
+More importantly: `docmd/architecture/numa_partition_runner.md` and `numa_worker_pools.md` document `PartitionRunner` (`obikindex/src/numa.rs`), **already implemented** and already used by `merge.rs`, `index.rs` (`build_layers`), `select.rs`, `reindex.rs`, `rebuild.rs` — one controller thread per NUMA node, a Rayon pool pinned to that node's CPUs (`hwlocality`, `numa` feature, default-on in `obikindex/Cargo.toml`), adaptive worker activation driven by *both* a CPU-efficiency signal and an I/O-throughput signal (`CpuSample`/`IoSample`, `/proc/self/io` on Linux). It exists precisely because a naive `into_par_iter()` on the global Rayon pool measurably degrades ×60 on this codebase's own 192-core/8-NUMA reference machine (`numa_worker_pools.md`, § Problem) once workers contend for cross-socket memory bandwidth on shared mmap'd/hashed structures — exactly the shape of the matrix-column scan in point 8 below.
+`obikmer` already depends on `obikindex` (`obikmer/Cargo.toml`, for `KmerIndex`), so `PartitionRunner` is directly reachable from `cmd/query.rs` — no new dependency. Both the partition-level loop and (see point 8) the genome-column scan should be driven through it rather than through ad-hoc `rayon::into_par_iter()`, to avoid reproducing the already-measured-and-fixed contention problem. Also relevant: the "CPU-only signal stalls on I/O-bound stages" issue documented for `pack_matrices` (mmap-heavy, page-fault-bound) applies just as much to a column-major mmap scan over persistent matrices — reuse the existing dual CPU/IO activation signal rather than re-deriving one.
+>
+> **Correction from implementation (Phase 4 below)**: this turned out not to be viable as described. `PartitionRunner::run()`'s actual body spawns roughly one OS thread per worker slot across every NUMA node **on every call** (confirmed by reading `numa.rs`, not just its doc comments) — fine for the one-call-per-command-invocation batch usage in `merge`/`build_layers`, but `query_partition_with` runs once per `(chunk, partition)`, far too frequently to absorb that spawn cost. Partition-level parallelism via `PartitionRunner` is deferred, not implemented. See Phase 4's "What did not ship, and why" for the detail.
+
+**8. Stage 2: column-major matrix fetch, parallel across genome columns — via `PartitionRunner`, not naive `rayon`.**
+Both persistent matrix formats are column-oriented on disk: `ColumnarCompactIntMatrix`/`ColumnarBitMatrix` (`obicompactvec/src/{intmatrix,bitmatrix}.rs`) mmap one file per genome column; `PackedCompactIntMatrix`/`PackedBitMatrix` mmap one region-offset per column in a single file. `fill_row(slot, buf)` as used today (`query.rs:262-272` via `on_hit`) reads **one slot across all `n_genomes` columns** per hit — the worst possible access pattern for this layout (up to `n_genomes` scattered mmap regions touched per single k-mer).
+Better: for each layer, walk the matrix **column by column** (genome by genome): for each genome, scan the `slot` keys collected in step 6 for that layer and call `col.get(slot)`, keeping only nonzero results, and broadcast to the associated `(seq_idx, pos)` list. Total `get()` calls are unchanged (`n_hits × n_genomes` in the worst case) — the win is locality (sequential access within one mmap'd column at a time, not scattered across all columns per hit), not fewer operations.
+Columns are independent (read-only, disjoint mmap regions) → embarrassingly parallel across genomes, *but* — per point 7 — `obicompactvec`'s existing `into_par_iter()` over `0..n_cols` (`sum()`, `count_nonzero()`, pairwise distance matrices) is the **naive, unpinned** pattern the rest of the codebase is actively migrating away from, not a model to copy here. Route this through `PartitionRunner` (or the same NUMA-pool machinery) instead. Two things to settle when this is designed: how the partition axis (point 7), the column axis, and the existing chunk-level `n_workers` `obipipeline` pool compose without oversubscribing the machine (three different concurrency mechanisms — raw-thread pipe workers, `PartitionRunner`'s pinned Rayon pools, and whatever drives the column scan — need a single reconciled thread budget, not three independent ones); and the threshold below which per-column dispatch overhead outweighs the gain (small `n_genomes` or small per-layer hit counts) — to be measured, not assumed.
+>
+> **Correction from implementation (Phase 4 below)**: column-major fetch is implemented — but as a plain sequential loop, not parallelised via `PartitionRunner`. Same reason as point 7's correction above. The column-major *locality* win (the actual claim of this point) does not depend on adding parallelism on top of it, and is validated independently. Column-level parallelism is deferred pending a mechanism that fits this call frequency (candidates noted in Phase 4).
+
+**9. Sparse per-genome representation, fed directly to Findere.**
+Stage 2's output should be `HashMap<genome_idx, Vec<(seq_idx, position, count)>>`, **sorted by `(seq_idx, position)`** once collected, instead of a dense `KmerResults`-style matrix — the key must carry `seq_idx`, not just `genome_idx`, because a chunk batches many sequences and `position` is only meaningful within one; a plain `Vec<(position, count)>` per genome would silently mix positions from different sequences and corrupt the sliding-window scan. This bounds retained memory by actual nonzero hits on both axes (position sparsity from non-matching k-mers, genome sparsity from a matched k-mer typically belonging to only a handful of genomes out of possibly many). The Findere sliding-window (`process_chunk`, the `win_min`/deque loop) would need reworking to run per `(sequence, genome)` over its sparse, sorted `(position, count)` list — detect runs of ≥`z` consecutive positions, window-min within each run — instead of today's dense `O(total_kmers × n_genomes)` scan. This is also a genuine complexity win (`O(hits log hits)` per genome vs. dense scan), not just memory.
+**Not covered by this sparsification**: `--detail`'s `cov` accumulator (`query.rs:304-308`) has the identical `n_genomes`-dense scaling problem and wasn't folded into points above. It doesn't need to be retained densely throughout processing, though — only the final JSON serialization (`emit_batch`) requires a dense `[u32]` per `(seq, genome)`, and only for the sequences actually being output with `--detail`. Densification can stay a late, output-time-only step, reconstructed from the sparse per-genome lists.
+
+**Secondary patterns available from `scatter.rs`/`superkmer.rs`, not yet in `query.rs`:**
+- `throttle()` + `CommonArgs::effective_max_open()` to bound concurrently-open input files (query.rs defines its own `QueryArgs`, doesn't reuse this).
+- Progress bar with EMA throughput + live active-worker gauges (`obisys::spinner`, `flat_active`/`transform_active` counters) — diagnostic value for locating the bottleneck.
+- `obisys::Reporter`/`Stage::start`/`stop` timing per phase (used by `index`, `filter`; absent from `query`).
+
+None of this is implemented yet — parked here as a coherent roadmap while the design is discussed further. Suggested dependency order: (1) I/O parallelism → (3) genome-aware chunk sizing → (4)–(9) staged/k-mer-deduped/NUMA-aware-partition-and-column-major/sparse query engine (larger refactor, biggest structural payoff — reuses `PartitionRunner` rather than inventing a new parallelism mechanism) → (2) parallel gzip (separate, orthogonal, tracked in chunkreader.md) → secondary diagnostics patterns.
+
+---
+
+## Implementation plan
+
+Concrete, phased translation of the roadmap above. Phases 0–2 are small, independent, low-risk, and each individually testable against current `query` output — land them first, in order, and measure on the reference 192-core/8-NUMA machine before deciding whether phases 3–5 (the staged/sparse engine, the larger structural payoff) are still worth their cost. Phases 3–5 are one coordinated change spanning `obikmer`, `obikpartitionner`, and `obicompactvec` — they should not be split across releases mid-way, because the intermediate state (e.g. k-mer-level dedup feeding the old dense `KmerResults`) has no correctness or performance benefit on its own. Phase 6 is unrelated to phases 0–5 and can happen any time, independently, if `rapidgzip-rs` is validated (see [chunkreader.md](../implementation/chunkreader.md#future-work--parallel-gzip-decompression-in-xopen)).
+
+Instrumentation is deliberately sequenced *before* the I/O fix (reordering the roadmap's own listed order), because every later phase's justification rests on a measurement ("to be measured, not assumed" appears throughout the roadmap above) — without it, phases 3–5 would be undertaken on faith.
+
+Performance measurement on the reference 192-core/8-NUMA machine is done by the project owner, not from this development environment (macOS, 16 cores — `PartitionRunner`'s NUMA pinning is Linux-only, so even phase 4's mechanism can't be functionally exercised for its actual purpose here). Each phase below is therefore written to be *self-measuring*: the debug-level logging it adds must be enough, on its own, to judge whether that phase's algorithmic choice paid off from a cluster run's logs, without needing to attach a profiler.
+
+### Conventions applied to every phase below
+
+**Debug logging.** Every phase that changes an algorithmic choice (not phase 0, which *is* the logging) adds `tracing::debug!`/`trace!` at points that let a cluster run's logs answer "did this help": counts, ratios, and timings that quantify the specific claim that phase makes — e.g. phase 3 must log how many MPHF `find` calls were saved by k-mer-level dedup (the whole justification for that phase), phase 4 must log per-column scan timings, phase 5 must log actual retained-memory / sparsity ratios achieved. Prefer one structured `debug!` per chunk (fields, not prose) over free-text — the cluster logs will be the only evidence available for judging these choices, so they need to be grep/awk-able, not just readable.
+
+**Unit tests.** This project's convention (`obiread`, `obikseq`, `obidebruinj`, `obicompactvec`, `obilayeredmap`, `obiskio`, `obifastwrite`) is `#[cfg(test)] #[path = "tests/<name>.rs"] mod tests;` at the bottom of the source file, with the actual test code in a sibling `src/tests/<name>.rs`. Neither `obikmer` nor `obikpartitionner` (the two crates phases 3 and 5 touch most) currently have a `src/tests/` directory at all — this needs creating, following the existing pattern exactly, not inventing a new one.
+
+**Workflow (`jj`).** Work happens in a fresh `jj` commit, easy to abandon. `jj new` between phases is reasonable where it helps isolate a phase for review, but only when the working copy compiles at that point (project convention) — phase 3's internal sub-steps (batch dedup change, then `query_layer.rs` split, then the new return shape) will likely not each compile independently since they're one coupled change, so treat "commit boundary" and "plan phase boundary" as related but not forced to match 1:1; use judgement per phase rather than mechanically splitting on every bullet.
+
+### Phase 0 — Instrumentation (prerequisite for measuring every later phase)
+
+**Goal**: make core utilization, throughput, and per-stage timing visible on a real run, so phases 1–5 can be justified with numbers instead of assumption.
+
+- `obikmer/src/cmd/query.rs`: wrap `run()`'s main loop with `obisys::Reporter`/`Stage::start("query")`/`.stop()`, printed at the end via `rep.print()` — same pattern as `index.rs`/`filter.rs`.
+- Add an `obisys::spinner("query")` progress bar around the `pipe.apply(...)` loop, with an EMA throughput readout (bases/s or k-mers/s, mirroring `steps::scatter`'s `ema_rate` computation, `scatter.rs:88-118`) and live gauges for "chunks in flight" / "workers busy" — reuse the `AtomicU32` counter pattern from `scatter.rs` (`flat_active`, `transform_active`) rather than inventing a new one.
+- Add `max_open_files: Option<usize>` to `QueryArgs` and a `effective_max_open()` method mirroring `CommonArgs::effective_max_open()` (`obikmer/src/cli.rs:90-94`) — needed by phase 1's `throttle()` call. (`QueryArgs` can't just embed `CommonArgs` — it doesn't take `kmer_size`/`minimizer_size`/`partitions`/`level_max`/`theta` from the CLI, those come from the index metadata — so this is a small standalone addition, not a flatten.)
+- Add one structured `debug!` per `process_chunk` call: chunk byte size, sequence count, s-mer count, wall time, and (once later phases exist) the fields they add — this single log line is the baseline every later phase's own logging gets compared against.
+- **Validation**: none needed beyond "the numbers appear and look sane" — this phase changes no query logic or output.
+- **Deliverable used by every phase below**: a before/after throughput and core-utilization measurement on the reference machine.
+
+### Phase 1 — Parallel per-file I/O (fixes root cause of low core utilization)
+
+**Goal**: file opening, decompression, and chunk-boundary parsing run across the `n_workers` pool instead of serially in the pipe's dedicated source thread.
+
+- `obikmer/src/cmd/query.rs`:
+  - Replace the `paths.into_iter().flat_map(read_sequence_chunks_sized(...))` construction (current `run()`, building `all_chunks`) with `obipipeline::throttle(paths.into_iter(), args.effective_max_open())`, passed as the pipe's `input`.
+  - Add a new `QueryData::Path(PathBuf)` variant (alongside `Chunk`/`Output`) to carry the throttled path through the pipe's type-erasure mechanism.
+  - Add a new **first** pipe stage, `Flat`/fallible (`||?`), modeled on `scatter.rs:60-86` and `superkmer.rs:54-65`: given a `Throttled<PathBuf>`, call `read_sequence_chunks_sized(path, chunk_bytes)` and yield each `Rope` chunk, keeping `pw.guard` alive until the file's iterator is exhausted (reuse or adapt `scatter.rs`'s `GuardedIter` wrapper — same lifetime problem, same fix).
+  - The existing `process_chunk` transform stage becomes the pipe's **second** stage, unchanged in its own logic — it still receives one `Rope` chunk at a time, just no longer all coming from one serial source.
+  - `make_pipe!` invocation grows from one stage (`Chunk => Output`) to two (`Path => Chunk => Output`).
+- Log, per file: time spent waiting on the `throttle()` slot (queueing due to `max_open`), and time spent opening/decompressing/producing the first chunk — this is what directly proves (or disproves) that I/O is now spread across workers instead of serialized.
+- **Validation**: run `query` on a small multi-file input, diff output against the pre-change version — content must be identical; **record order across files is not guaranteed to be preserved** even before this change (chunk-level dispatch across `n_workers` already reorders completions), so the diff must be order-insensitive (sort by read id, or compare as sets) if it wasn't already.
+- **Measure**: core utilization on the reference machine with several large input files, compare against phase 0's baseline.
+
+### Phase 2 — Genome-aware chunk-size formula (fixes OOM)
+
+**Goal**: `chunk_bytes` reflects actual per-chunk memory (`O(n_genomes)`), not a fixed multiplier.
+
+- `obikmer/src/cmd/query.rs`, `run()`: `n_genomes` and `args.detail` are already computed above the `chunk_bytes` calculation (`n_genomes` at the top of `run()`, before line 407 in the current file) — reorder if needed, then replace:
+  ```rust
+  let computed = avail / (n_workers as u64 * 16);
+  ```
+  with a formula that scales the divisor by `n_genomes` (and roughly doubles it when `--detail` is set, since `cov` duplicates the per-genome accumulation): e.g. `per_chunk_multiplier = base_overhead + n_genomes as u64 * BYTES_PER_KMER_PER_GENOME * if detail { 2 } else { 1 }`, replacing the flat `16`. `BYTES_PER_KMER_PER_GENOME` should be derived from `KmerResults`'s actual layout (`4` bytes per `u32` entry in `data`, plus the `bool` in `in_index`, plus `win_min`'s equal-sized buffer) rather than guessed.
+  - `args.chunk_size` (manual `--chunk-size` override) keeps taking priority, unchanged.
+- Log the resolved `chunk_bytes`, `n_genomes`, and the estimated peak per-chunk memory (`chunk_bytes` × the same multiplier used to derive it) once at startup — lets a cluster run confirm the estimate was actually respected, not just that the process didn't get OOM-killed (which could also happen to be true for the wrong reason).
+- **Validation**: build a test index with a large `n_genomes` (e.g. hundreds), run `query` with default chunk sizing under a memory limit (`ulimit -v` or a cgroup), confirm it no longer gets OOM-killed and that memory scales as predicted when `n_genomes` grows.
+- **Note**: this phase is superseded once phase 5 lands (sparse retained memory no longer scales with `n_genomes × total_kmers` at all) — but it's needed immediately regardless, since phases 3–5 are a bigger, riskier change and users need a working `query` in the meantime.
+
+### Phase 3 — K-mer-level dereplication, staged MPHF/matrix lookup
+
+**Goal**: replace superkmer-level dedup with k-mer-level dedup (roadmap point 5), and split the fused MPHF-find/matrix-fetch (point 4) so stage 1's output is bucketed by layer and MPHF slot (point 6).
+
+- `obikmer/src/cmd/query.rs`:
+  - Replace `QueryBatch::from_records`'s dedup map (`HashMap<RoutableSuperKmer, Vec<SKDesc>>`, current `query.rs:112`) with a per-partition `HashMap<CanonicalKmer, Vec<(seq_idx: u32, pos: u32)>>`, built in the same `SuperKmerIter` pass: superkmer construction and partition routing (`part_idx` from the superkmer's minimizer hash) are unchanged, only the granularity of what gets deduplicated changes — each `CanonicalKmer` within a superkmer is inserted individually instead of the whole superkmer being the dedup key.
+  - **Verified**: `CanonicalKmer` (`obikseq/src/kmer.rs:390`, `pub type CanonicalKmer = CanonicalKmerOf<KLen>`) — the underlying `CanonicalKmerOf<L>` derives `Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash` (`kmer.rs:269`). Usable as a `HashMap`/`HashSet` key as-is, no change needed.
+- `obikpartitionner/src/query_layer.rs`:
+  - Split `QueryLayer::find_into` (`query_layer.rs:48-67`) into two methods: `find_slot(&self, kmer: CanonicalKmer) -> Option<usize>` (MPHF only, no matrix touch) and keep `fill_row` as-is for phase 4 to call later.
+  - Replace `query_partition_with`'s inner loop (`query_layer.rs:103-113`) with a version that, for each unique `CanonicalKmer`, calls `find_slot` across the partition's layers (stopping at first hit, same as today), and instead of immediately filling a row, records `(layer_idx, slot)`.
+  - New return shape for the partition-level query, replacing today's `on_hit(sk_idx, kmer_idx, row)` callback: `HashMap<layer_idx, HashMap<slot, Vec<(seq_idx, pos)>>>` (roadmap point 6) — built directly from the k-mer dedup map's `Vec<(seq_idx,pos)>` values, keyed by the resolved slot instead of the k-mer.
+- **This phase alone has no throughput benefit yet** (matrix fetch still happens, just deferred) beyond the k-mer-level dedup itself (fewer MPHF calls when queries have overlapping/repeated k-mers) — its purpose is to produce the input phase 4 needs. Land phase 3+4 together, not phase 3 alone, per the "don't split 3–5 across releases" note above.
+- Log, per chunk: total k-mer occurrences vs. unique `CanonicalKmer` count (the dedup ratio — the entire justification for this phase) and the resulting MPHF `find` call count. If the dedup ratio is close to `1.0` on real query data (little redundancy), that's the cluster run telling us this phase wasn't worth it — the logging needs to be able to say that, not just confirm the happy path.
+- **Unit tests**: create `obikmer/src/cmd/tests/query.rs` (new `src/tests/` dir for this crate, following the project's `#[cfg(test)] #[path = "tests/query.rs"] mod tests;` convention) and `obikpartitionner/src/tests/query_layer.rs` (likewise new for this crate). Cover: the k-mer-level dedup map construction on synthetic sequences with known repeated/overlapping k-mers (assert unique-kmer count and occurrence lists); the `find_slot`/bucket-by-layer-and-slot construction against a small hand-built `QueryLayer` fixture, asserting the `(layer_idx, slot, seq_idx, pos)` tuples match what the old per-occurrence loop would have produced.
+
+### Phase 4 — Column-major matrix fetch (roadmap points 7–8) — implemented, NUMA parallelism deferred
+
+**Goal (revised during implementation)**: replace `fill_row`-per-hit (row-major, worst-case mmap locality) with a column-major scan. `PartitionRunner` turned out to be the wrong mechanism for this at this call granularity — see below; the column-major fetch itself is implemented and validated, without it.
+
+**What shipped:**
+- `obicompactvec`: the per-column accessors this phase needed **already existed** — `PersistentCompactIntMatrix::col_view(c)` and `PersistentBitMatrix::col_view(c)` are public, and `IntSliceView::get(slot)`/`BitSliceView::get(slot)` are public — the original plan underestimated how much of this plumbing the pairwise-distance code (`dump`/`select`/`stats`) had already required. The one real gap: `PersistentBitMatrix::col_view()` panics on the `Implicit` variant (the documented mono-genome fast path, `bitmatrix.rs`). Added `PersistentBitMatrix::get(c, slot) -> u32` (`bitmatrix.rs`), a non-panicking column-major point lookup that returns `1` for `Implicit` regardless of `c` — the smallest surface needed, not a new `col_get` API from scratch.
+- `obikpartitionner/src/query_layer.rs`: `query_partition_with` is now two explicit stages, matching roadmap points 6–8: **stage 1** (MPHF-only, per unique k-mer, bucket hits by `(layer_idx, slot)`, emits `QueryHit::Found`) then **stage 2** (per layer with ≥1 hit, column-major: for each genome column `g` in `0..layer.n_cols().min(n_genomes)`, scan that layer's bucketed slots and call `col_value(g, slot)`, emitting `QueryHit::Value(descs, g, value)` on nonzero). `QueryHit` is a single enum delivered through one `FnMut(QueryHit)` callback — an earlier two-closure design (`on_found` + `on_value`) didn't borrow-check, since the caller's single mutable accumulator (`KmerResults`) can't be captured by two separate `FnMut` closures passed to the same call.
+- `obikmer/src/cmd/query.rs`: `KmerResults::set` (row-major, whole-row-at-once) replaced by `mark_found` (stage 1: flag a position as indexed, independent of any genome's value) and `set_one` (stage 2: write one genome's value at one position). `QueryStats` extended with `n_columns_scanned`/`n_col_get_calls`, logged per chunk.
+- Total `get()`-equivalent calls are unchanged from the row-major version (`n_hits × n_cols` in the worst case, confirmed by `n_col_get_calls` in the debug log) — the win is locality (sequential access within one layer's column at a time, across `mmap`'d regions, instead of jumping across all columns per hit), exactly as predicted.
+
+**What did not ship, and why — `PartitionRunner` is architecturally the wrong tool here:**
+Reading `obikindex/src/numa.rs`'s actual `run()` body (not just its doc comments) shows every call spawns a timer thread **plus one OS thread per worker slot on every NUMA node** (`std::thread::scope` + one `s.spawn()` per node per `max_workers`) — on the 192-core/8-NUMA reference machine, that's on the order of 190+ fresh OS threads spawned **per call**. This is fine for its actual, established usage in this codebase (`merge.rs`, `index.rs`'s `build_layers`): one `PartitionRunner::new()` + one `run()` call per command invocation, amortised over a batch of ~256 long-running partitions. It is not fine for `query`'s call pattern: `query_partition_with` runs once per `(chunk, partition)`, potentially thousands of times per second — spawning ~190 OS threads that often to scan a handful of genome columns would very likely cost far more than the row-major approach it's meant to replace. This is exactly the "resolve empirically, don't assume" composition risk the roadmap flagged, just resolved by reading the mechanism's actual cost before wiring it in, rather than by measuring a regression on the cluster after the fact.
+The column-major loop in stage 2 is therefore a **plain sequential loop** for now — it captures the whole, provable locality win (roadmap point 8's actual claim) without adding any parallelism mechanism. Genome-column-level parallelism (point 8's "bonus" axis) and partition-level parallelism (point 7) are both deferred — not abandoned. Candidates for a follow-up, once there's a concrete profiling need: (a) `rayon`'s already-warm global pool (`into_par_iter()`) for the column axis specifically — cheap to invoke repeatedly since it doesn't spawn threads per call, though it's the same "naive rayon" pattern `numa_worker_pools.md` warns about for a *different* workload (random pointer-chasing over large hash maps); a column scan's access pattern (sequential reads within one `mmap`'d region) has a different contention profile and hasn't been shown to have the same problem — needs its own measurement, not an assumption either way; (b) restructuring so `PartitionRunner` is invoked once per whole `query` run (or per large batch of chunks) rather than per `(chunk, partition)`, amortising its spawn cost the way `merge`/`build_layers` do — a bigger structural change than this phase's scope.
+- Log (implemented): `QueryStats::n_columns_scanned`/`n_col_get_calls`, folded into the existing per-chunk `debug!("k-mer dedup + column-major fetch", ...)` line (`query.rs`) alongside phase 3's dedup counters.
+- **Unit tests**: extended `obikpartitionner/src/tests/query_layer.rs` (phase 3's file) — `query_partition_with`'s empty/missing-index paths updated for the new `QueryStats` fields and single-callback signature.
+- **Validation performed**: full workspace build + `cargo test --workspace`, zero failures. Functional validation against real indexes: (1) a single-genome index — output byte-identical to pre-phase-4 (same `kmer_count`/`kmer_strict_matches` on every record); (2) the existing 20-genome `benchmark/global_index_presence` index — runs correctly, `n_hits=0` for an unrelated query (expected: no shared k-mers between a plant read and a bacterial reference set), no panics, confirming the `Implicit`/multi-column bounds logic doesn't crash on a real multi-genome, mixed-format index; (3) **the critical correctness case**: built two single-sequence-pair test genomes, merged into one 2-genome index, queried with reads from both — reads from `genomeA` matched **only** `genomeA` (`kmer_count` identical to the pre-dedup occurrence count, zero leakage into `genomeB`'s column) and vice versa. This is the test that would have caught a column-index mixup, an off-by-one in `n_cols`, or cross-genome bleed from the stage-1/stage-2 split — it passed cleanly.
+- **Not yet done**: the microbenchmark comparing column-major vs. the old row-major access pattern's wall time / page-fault counters on a large-`n_genomes` layer — needs a realistically large multi-genome index and, for the page-fault counters specifically, Linux (not available from this development environment). Left for cluster validation alongside phases 1–3's own pending measurements.
+
+### Phase 5 — Sparse Findere rework (roadmap point 9)
+
+**Goal**: replace the dense `KmerResults`/`win_min` sliding-window scan with one operating on phase 4's sparse per-genome output.
+
+- `obikmer/src/cmd/query.rs`, `process_chunk`:
+  - Remove `KmerResults` (`query.rs:157-202`) and the dense `win_min` allocation (`query.rs:290-291`, sized `max_n_kmers × n_genomes`).
+  - Keep a lightweight dense `in_index: Vec<bool>` per chunk (sized `total_kmers`, independent of `n_genomes`) from phase 3's stage 1 — still needed for `kmer_missing` bookkeeping (leftmost-s-mer-of-window membership test), which phase 4's sparse structure doesn't carry (a k-mer with no genome hit has no entry there at all).
+  - New per-`(seq_idx, genome)` scan: for each genome's `Vec<(seq_idx, pos, count)>` (sorted, per phase 4), group by `seq_idx` (contiguous after sort), then within each sequence's positions detect runs of `pos, pos+1, pos+2, ...` of length ≥ `z`; within each run, the existing monotone-deque window-minimum logic (`query.rs`'s current `dq` loop, conceptually unchanged) applies — but the deque now only scans real entries in the run, never zero-filled gaps.
+  - Update `SeqAcc` accumulation and `emit_batch` to consume this per-genome sparse iteration instead of `results.val`/`results.is_in_index`.
+  - `--detail`/`cov`: build sparsely during the same scan (only positions with a confirmed contribution get an entry), densify into the `[u32]` JSON array only in `emit_batch`, only for genomes/sequences actually being serialized (per roadmap point 9's note, `query.rs:304-308`'s current dense allocation goes away).
+- Log, per chunk: total sparse entries retained vs. what the old dense `KmerResults` would have allocated (`total_smers × n_genomes`) — the sparsity ratio is this phase's entire reason for existing, so it must be directly visible in the logs, not inferred from process RSS. Also log the run-detection stats (number of runs found, average run length) — a low average run length relative to `z` would mean most positions still fail to form a full window, worth knowing.
+- **Unit tests**: `obikmer/src/cmd/tests/query.rs` (extended from phase 3) — the property test described below is the primary deliverable here, not an afterthought; write it as an actual `#[test]` (or a small internal fuzz/property-style loop over randomized fixtures if a property-testing crate isn't already a dependency — check before adding one, per this project's dependency-approval rule) rather than a one-off manual comparison.
+- **Validation — this is the correctness-critical phase**: property-test comparing old (dense, pre-phase-3) and new (sparse) implementations on the same randomized input/index fixtures, asserting identical `kmer_count`, `kmer_missing`, `kmer_strict_matches`, and (with `--detail`) `coverage` for every sequence. Keep both implementations compiled side by side (behind a debug-only flag or a temporary parallel code path) only for the duration of this validation; delete the dense path once parity is confirmed — per this project's own convention, superseded code is not kept "just in case."
+- **Update `docmd/architecture/query.md` itself**: once this phase lands, the "Findere z-window filter" section (which currently — correctly — describes the dense deque-over-`0..n_smers` scan) needs another pass to describe the sparse run-detection algorithm instead, as already flagged when this phase was discussed.
+
+**Implemented as planned, no deviations discovered this time.** What shipped:
+- `KmerResults` removed entirely, replaced by `SmerIndex` (`in_index: Vec<bool>` + `offsets`, unchanged size/purpose, renamed since it's no longer "results" — just the O(1)-per-position "was this k-mer found at all" bookkeeping) and `by_genome: Vec<Vec<(seq_idx, pos, value)>>` (one empty `Vec` per genome until a hit arrives — genomes with zero hits in a chunk cost nothing beyond the outer `Vec`'s own allocation).
+- New `sparse_findere_for_genome(hits, z, presence, threshold) -> (Vec<ConfirmedHit>, n_runs, total_run_len)` (`query.rs`): sorts one genome's raw hits by `(seq_idx, pos)`, detects maximal runs of consecutive `pos` within one sequence, runs the same monotone-deque window-minimum as before but scoped to each run (run-relative indices for eviction, absolute `pos` for computing `pos_out`). Presence/count adjustment (`u32::from(win_min >= threshold)` vs. raw) is applied inside this function, once per confirmed hit, rather than later during accumulation.
+- `process_chunk` restructured into three passes after the partition loop: (1) run `sparse_findere_for_genome` per genome, collecting `confirmed_by_genome` and run-detection stats; (2) accumulate `genome_totals` directly from `confirmed_by_genome` and mark a `confirmed_any: Vec<bool>` (sized `total_kmers_out`, not `× n_genomes`); (3) a position-only pass (`O(total_kmers_out)`, no genome factor) computing `kmer_count`/`kmer_missing` from `confirmed_any` + `SmerIndex`. `cov` (`--detail`) is populated by re-scanning `confirmed_by_genome` — only when `--detail` is actually set, otherwise skipped entirely.
+- Debug log added (`"sparse Findere"`): `n_dense_would_be` (`n_occurrences × n_genomes` — what the deleted dense path would have allocated), `n_sparse_entries` (what's actually retained), `n_runs`/`avg_run_len` (per the plan's ask, to see whether hits mostly fail to form complete windows).
+- **Unit tests**: `sparse_findere_matches_dense_reference_on_random_inputs` (`obikmer/src/cmd/tests/query.rs`) — 200 randomized cases (sequence count/length, `z`, presence/count mode, threshold, hit density from sparse to fully-dense) comparing `sparse_findere_for_genome` against `dense_reference_findere`, a faithful reimplementation of the deleted dense algorithm kept only as a test-local correctness oracle (no property-testing crate added — checked first, none was a workspace dependency; a small `std`-only xorshift64 PRNG stands in for one, deterministic and dependency-free). All 200 cases pass.
+- **Functional validation performed**: full workspace build + `cargo test --workspace`, zero failures. End-to-end against real indexes: baseline output (no flags) unchanged from pre-phase-5 recorded values on the same fixtures; `--count-missing` correct (`kmer_missing: 0` on a self-match); `--detail` correct — coverage array length matches `kmer_count`, and critically, re-ran the two-genome cross-contamination check from phase 4 with `--detail --count-missing`: `genomeA` reads show coverage sum `106` for `genomeA` and `0` for `genomeB` (and vice versa) — confirms the sparse-to-dense `cov` reconstruction doesn't leak across genomes either, not just the scalar `kmer_strict_matches` path.
+- This phase's roadmap item ("update the Findere z-window filter section") — done, see above; the "Algorithm" section's pseudocode was also updated, since it still named `KmerResults`/`SKDesc` from before phases 3–4.
+
+### Phase 6 — Parallel gzip decompression (independent, optional)
+
+Tracked separately in [chunkreader.md](../implementation/chunkreader.md#future-work--parallel-gzip-decompression-in-xopen); parked pending validation of `rapidgzip-rs` on real data. Not a dependency of, or a dependency for, phases 0–5 — `xopen` is shared infrastructure (`obiread`), phase 1 benefits from it but doesn't require it (phase 1 parallelises *across* files; this phase would additionally parallelise *within* one large file).
+
+### Cross-cutting risks
+
+- **Thread-budget oversubscription** (phase 4): the single biggest unresolved design question in this whole plan — see phase 4's composition note. Should be settled with real measurements early in phase 4, not assumed from the design alone.
+- **`obicompactvec` API surface growth** (phase 4): new public per-column accessors are additive (existing `fill_row`/`row` stay for other callers — `dump`, `select`, distance computations) — no breaking change expected, but worth checking `obicompactvec`'s other callers aren't already relying on `fill_row` being the only/cheapest access path in a way that would make maintaining two access patterns (row-major and column-major) a real maintenance cost rather than a one-off addition.
+- **`PersistentBitMatrix::Implicit`'s hardcoded `n_cols: 1` — resolved, not a bug.** `LayerMeta`'s own doc comment (`obicompactvec/src/layer_meta.rs:1-9`) states it is written "alongside `mphf.bin`" and read by `PersistentBitMatrix::open` "to determine `n_rows` for **the implicit (mono-genome presence/absence) case**" — i.e. `Implicit` is a documented single-genome fast path (no presence matrix needed when there is trivially one genome), not a generic "no matrix built yet" fallback. `n_cols: 1` is correct by design for the case it's meant to handle. Phase 4's column loop is safe as planned — this was worth checking once, doesn't need further action.

docmd/implementation/chunkreader.md

@@ -107,3 +107,19 @@ stateDiagram-v2
 `restart` is updated each time a `+` is found. When any state fails its expected input, the scan jumps back to `restart` and continues from there — guaranteeing that a `@` in a quality line cannot be accepted as a record start, because the `\n+\n` structure immediately following it (going backward) will not be found.
 
 Returns the byte offset of the `@` that starts the last complete record.
+
+---
+
+## Future work — parallel gzip decompression in `xopen`
+
+`obiread::xopen` (`xopen.rs`) decompresses gzip via `niffler` → `flate2`, which is single-threaded (standard DEFLATE has no parallel-decodable structure). For large local gzip inputs this single-threaded decompression can become the throughput bottleneck feeding the `query`/`index`/`superkmer` pipelines, since chunk/page production for a given file is serialized ahead of the worker pool.
+
+Candidate: special-case local, on-disk, gzip-magic-detected paths in `open_raw`/`xopen` to use [`rapidgzip-rs`](https://github.com/alekseizarubin/rapidgzip-rs) (`ReaderBuilder::new().parallelism(n).open(path)`, implements `Read + Seek`) instead of `niffler`, keeping `niffler` for every other case: `stdin` (`-`), HTTP(S) sources, and all non-gzip formats (bzip2, xz, zstd — less used in practice here).
+
+Constraints identified so far (not yet validated against real data):
+- Branch point must move earlier than the current `decompress()` call in `open_raw` — rapidgzip's fast path needs the file **path**, not an already-opened generic `Read`, so the gzip/local-file detection has to happen before the generic `File::open` + `niffler::send::get_reader` path is taken.
+- `stdin` and HTTP sources are not seekable — they stay on `niffler` regardless; the gain only applies to local on-disk `.gz` files.
+- `rapidgzip-sys` vendors a native C++ engine: requires CMake ≥ 3.17, a C++17 compiler, and `nasm` on x86 targets — a real build-toolchain addition, not just a pure-Rust crate.
+- Low maturity of the Rust binding at review time (2 GitHub stars, ~15 commits, April 2026 latest release) — the underlying C++ engine is validated (HPDC 2023 paper), but the binding itself has limited production track record.
+
+Decision: parked for now. Before adopting, validate on real data: throughput vs. `niffler` on representative large `.gz` inputs, and byte-for-byte correctness of decompressed output.

src/Cargo.lock

@@ -1704,7 +1704,7 @@ dependencies = [
 
 [[package]]
 name = "obikmer"
-version = "1.1.6"
+version = "1.1.37"
 dependencies = [
  "clap",
  "csv",

src/obicompactvec/src/bitmatrix.rs

@@ -1,5 +1,5 @@
 use std::fs::{self, File};
-use std::io::{self, BufWriter, Write as _};
+use std::io::{self, BufWriter, Read as _, Write as _};
 use std::path::{Path, PathBuf};
 
 use memmap2::Mmap;
@@ -171,19 +171,43 @@ impl PackedBitMatrix {
     }
 }
 
+/// Reads just the `n_cols` field from an existing packed matrix's header,
+/// without mapping the file. Used by `pack_bit_matrix` to tell a genuinely
+/// complete pack from a stale one that predates a later column-widening.
+fn packed_bit_matrix_n_cols(path: &Path) -> io::Result<usize> {
+    let mut f = File::open(path)?;
+    let mut header = [0u8; PBMX_HEADER];
+    f.read_exact(&mut header)?;
+    Ok(u64::from_le_bytes(header[16..24].try_into().unwrap()) as usize)
+}
+
 /// Build `presence/matrix.pbmx` from existing `col_*.pbiv` files.
 pub fn pack_bit_matrix(dir: &Path) -> io::Result<()> {
     let packed_path = dir.join("matrix.pbmx");
-    if packed_path.exists() {
+
-        // Matrix complete; remove any leftover column files from a killed cleanup.
+    let meta = match MatrixMeta::load(dir) {
-        if let Ok(meta) = MatrixMeta::load(dir) {
+        Ok(meta) => meta,
+        Err(e) => {
+            // No columnar data pending: either this layer was already
+            // packed and cleaned up (matrix.pbmx complete, nothing left to
+            // do), or genuinely nothing was ever written here.
+            return if packed_path.exists() { Ok(()) } else { Err(e) };
+        }
+    };
+
+    // A `matrix.pbmx` can already exist here even though columnar data is
+    // still pending — e.g. copied verbatim from a merge's base source
+    // before this layer was widened with more genome columns (see
+    // `obikpartitionner::merge_partition`). Only skip (re-)packing if the
+    // existing file already reflects the current column count; otherwise
+    // the columnar files are newer and must be (re-)packed, overwriting the
+    // stale one — never silently discarded as "leftover cleanup".
+    if packed_bit_matrix_n_cols(&packed_path).ok() == Some(meta.n_cols) {
         for c in 0..meta.n_cols { let _ = fs::remove_file(col_path(dir, c)); }
         let _ = fs::remove_file(dir.join("meta.json"));
-        }
         return Ok(());
     }
 
-    let meta = MatrixMeta::load(dir)?;
     let n_cols = meta.n_cols;
 
     // Compute offsets from file sizes — no column data loaded into RAM.
@@ -294,6 +318,19 @@ impl PersistentBitMatrix {
         }
     }
 
+    /// Column-major point lookup: value at column `c`, slot `slot`, as 0/1.
+    ///
+    /// Unlike [`col_view`](Self::col_view), this never panics on `Implicit`
+    /// (every column reads as present, per the mono-genome fast path) — safe
+    /// to call for any `c < self.n_cols()`.
+    pub fn get(&self, c: usize, slot: usize) -> u32 {
+        match self {
+            Self::Columnar(m) => m.col(c).get(slot) as u32,
+            Self::Packed(m)   => m.col_slice(c).get(slot) as u32,
+            Self::Implicit { .. } => 1,
+        }
+    }
+
     pub fn col_persist(&self, c: usize, path: &Path) -> io::Result<PersistentBitVecBuilder> {
         match self {
             Self::Columnar(m) => PersistentBitVecBuilder::build_from(m.col(c), path),
@@ -500,17 +537,26 @@ where T: Clone + Default {
 }
 
 /// Compute a symmetric `n×n` matrix in parallel by evaluating `f(i,j)` for
-/// all upper-triangle pairs. `T: Copy` avoids the `.clone()` needed for the
+/// all upper-triangle pairs, plus `f(i,i)` for the diagonal. `T: Copy` avoids
-/// lower-triangle mirror.
+/// the `.clone()` needed for the lower-triangle mirror.
+///
+/// The diagonal is *not* generally `T::default()`: for a self-comparison,
+/// `f(i,i)` is often the column's own weight (e.g. intersection-with-self —
+/// see `pairwise2_matrix`), not zero. Distance finalisations that need a
+/// zero diagonal (self-distance) already overwrite it explicitly.
 pub(crate) fn pairwise_matrix<T>(n: usize, f: impl Fn(usize, usize) -> T + Sync) -> Array2<T>
 where T: Copy + Default + Send {
     let results: Vec<(usize, usize, T)> = upper_pairs(n)
         .into_par_iter().map(|(i, j)| (i, j, f(i, j))).collect();
-    fill_symmetric(n, results.into_iter().map(|(i, j, v)| (i, j, v, v)))
+    let mut m = fill_symmetric(n, results.into_iter().map(|(i, j, v)| (i, j, v, v)));
+    for i in 0..n { m[[i, i]] = f(i, i); }
+    m
 }
 
 /// Same as `pairwise_matrix` but `f` returns two values that fill two
 /// symmetric matrices simultaneously (e.g. intersection + union for Jaccard).
+/// The diagonal is `f(i,i)` (e.g. a genome's kmer count intersected with
+/// itself), not `T::default()` — see `pairwise_matrix` for why that matters.
 pub(crate) fn pairwise2_matrix<T>(n: usize, f: impl Fn(usize, usize) -> (T, T) + Sync) -> (Array2<T>, Array2<T>)
 where T: Copy + Default + Send {
     let results: Vec<(usize, usize, T, T)> = upper_pairs(n)
@@ -523,5 +569,10 @@ where T: Copy + Default + Send {
         m0[[i, j]] = a; m0[[j, i]] = a;
         m1[[i, j]] = b; m1[[j, i]] = b;
     }
+    for i in 0..n {
+        let (a, b) = f(i, i);
+        m0[[i, i]] = a;
+        m1[[i, i]] = b;
+    }
     (m0, m1)
 }

src/obicompactvec/src/intmatrix.rs

@@ -1,5 +1,5 @@
 use std::fs::{self, File};
-use std::io::{self, BufWriter, Write as _};
+use std::io::{self, BufWriter, Read as _, Write as _};
 use std::path::{Path, PathBuf};
 
 use memmap2::Mmap;
@@ -228,17 +228,44 @@ impl PackedCompactIntMatrix {
     }
 }
 
+/// Reads just the `n_cols` field from an existing packed matrix's header,
+/// without mapping the file. Used by `pack_compact_int_matrix` to tell a
+/// genuinely complete pack from a stale one that predates a later
+/// column-widening.
+fn packed_int_matrix_n_cols(path: &Path) -> io::Result<usize> {
+    let mut f = File::open(path)?;
+    let mut header = [0u8; PCMX_HEADER];
+    f.read_exact(&mut header)?;
+    Ok(u64::from_le_bytes(header[16..24].try_into().unwrap()) as usize)
+}
+
 /// Build `counts/matrix.pcmx` from existing `col_*.pciv` files.
 pub fn pack_compact_int_matrix(dir: &Path) -> io::Result<()> {
     let packed_path = dir.join("matrix.pcmx");
-    if packed_path.exists() {
+
-        if let Ok(meta) = MatrixMeta::load(dir) {
+    let meta = match MatrixMeta::load(dir) {
+        Ok(meta) => meta,
+        Err(e) => {
+            // No columnar data pending: either this layer was already
+            // packed and cleaned up (matrix.pcmx complete, nothing left to
+            // do), or genuinely nothing was ever written here.
+            return if packed_path.exists() { Ok(()) } else { Err(e) };
+        }
+    };
+
+    // A `matrix.pcmx` can already exist here even though columnar data is
+    // still pending — e.g. copied verbatim from a merge's base source
+    // before this layer was widened with more genome columns (see
+    // `obikpartitionner::merge_partition`). Only skip (re-)packing if the
+    // existing file already reflects the current column count; otherwise
+    // the columnar files are newer and must be (re-)packed, overwriting the
+    // stale one — never silently discarded as "leftover cleanup".
+    if packed_int_matrix_n_cols(&packed_path).ok() == Some(meta.n_cols) {
         for c in 0..meta.n_cols { let _ = fs::remove_file(col_path(dir, c)); }
         let _ = fs::remove_file(dir.join("meta.json"));
-        }
         return Ok(());
     }
-    let meta   = MatrixMeta::load(dir)?;
+
     let n_cols = meta.n_cols;
     let col_sizes: Vec<u64> = (0..n_cols)
         .map(|c| fs::metadata(col_path(dir, c)).map(|m| m.len()))

src/obikindex/Cargo.toml

@@ -17,4 +17,8 @@ serde            = { version = "1", features = ["derive"] }
 serde_json       = "1"
 indicatif        = "0.17"
 tracing          = "0.1.44"
-hwlocality       = { version = "1.0.0-alpha.11", features = ["vendored"] }
+hwlocality       = { version = "1.0.0-alpha.11", features = ["vendored"], optional = true }
+
+[features]
+default = ["numa"]
+numa    = ["hwlocality"]

src/obikindex/src/numa.rs

@@ -5,45 +5,48 @@
 // CPUs. Linux first-touch policy then places graph allocations in local DRAM
 // automatically — no explicit memory binding needed.
 //
-// Returns None when:
+// UMA systems (single socket, Apple Silicon, etc.) are the degenerate case:
-//   - hwloc topology initialisation fails
+// one synthetic node containing all cores, no pool, no pinning.
-//   - the system has only one NUMA node (UMA, Apple Silicon, single-socket)
-//   - any per-node pool fails to build
 
 use std::sync::Arc;
 use std::time::{Duration, Instant};
 
 use crossbeam_channel::unbounded;
+#[cfg(feature = "numa")]
 use hwlocality::Topology;
+#[cfg(feature = "numa")]
 use hwlocality::cpu::binding::CpuBindingFlags;
+#[cfg(feature = "numa")]
 use hwlocality::cpu::cpuset::CpuSet;
+#[cfg(feature = "numa")]
 use hwlocality::object::types::ObjectType;
+use obisys::{CpuSample, IoSample};
 use tracing::debug;
 
 // ── Public interface ──────────────────────────────────────────────────────────
 
 pub struct NumaSetup {
-    pub pools: Vec<Arc<rayon::ThreadPool>>,
+    /// One entry per NUMA node. `None` on UMA systems (no pool, no pinning).
+    pub pools: Vec<Option<Arc<rayon::ThreadPool>>>,
     /// CPU indices for each NUMA node, in node order.
     pub cpus_per_node: Vec<Vec<usize>>,
 }
 
 impl NumaSetup {
-    /// Workers to activate per NUMA node.
+    /// Maximum worker slots per node (one per physical core in the node).
-    /// Empirically ~3 workers saturate one node's memory bandwidth.
     pub fn workers_per_node(&self) -> usize {
         self.cpus_per_node
             .first()
-            .map(|c| (c.len() / 8).max(3).min(8))
+            .map(|c| c.len().max(1))
-            .unwrap_or(3)
+            .unwrap_or(1)
     }
 }
 
 /// Detect NUMA topology and build per-node Rayon pools.
-/// Returns None on UMA systems, single-node machines, or on failure.
+/// Always succeeds: falls back to a single synthetic UMA node on failure.
-pub fn build() -> Option<NumaSetup> {
+#[cfg(feature = "numa")]
-    let topology = Topology::new().ok()?;
+pub fn build() -> NumaSetup {
-
+    if let Ok(topology) = Topology::new() {
         let nodes: Vec<Vec<usize>> = topology
             .objects_with_type(ObjectType::NUMANode)
             .filter_map(|obj| obj.cpuset())
@@ -56,28 +59,55 @@ pub fn build() -> Option<NumaSetup> {
             .filter(|v| !v.is_empty())
             .collect();
 
-    if nodes.len() <= 1 {
+        if nodes.len() > 1 {
-        return None;
+            if let Some(pools) = nodes
-    }
+                .iter()
-
+                .map(|cpus| build_pool(cpus).map(|p| Some(Arc::new(p))))
+                .collect::<Option<Vec<_>>>()
+            {
                 debug!(
                     "NUMA topology: {} node(s), {} core(s)/node",
                     nodes.len(),
                     nodes.first().map_or(0, |v| v.len()),
                 );
+                return NumaSetup {
+                    pools,
+                    cpus_per_node: nodes,
+                };
+            }
+        }
+    }
 
-    let pools = nodes
+    // UMA fallback: single synthetic node, all cores, no pool, no pinning.
-        .iter()
+    let n_cores = std::thread::available_parallelism()
-        .map(|cpus| build_pool(cpus).map(Arc::new))
+        .map(|n| n.get())
-        .collect::<Option<Vec<_>>>()?;
+        .unwrap_or(1);
+    debug!("UMA: single synthetic node, {} core(s)", n_cores);
+    NumaSetup {
+        pools: vec![None],
+        cpus_per_node: vec![(0..n_cores).collect()],
+    }
+}
 
-    Some(NumaSetup { pools, cpus_per_node: nodes })
+#[cfg(not(feature = "numa"))]
+pub fn build() -> NumaSetup {
+    let n_cores = std::thread::available_parallelism()
+        .map(|n| n.get())
+        .unwrap_or(1);
+    debug!("UMA: single synthetic node, {} core(s)", n_cores);
+    NumaSetup {
+        pools: vec![None],
+        cpus_per_node: vec![(0..n_cores).collect()],
+    }
 }
 
 /// Bind the calling thread to `cpu_indices` using hwloc.
 /// Silently returns on any error so the thread still runs, just unbound.
+#[cfg(feature = "numa")]
 pub fn pin_current_thread(cpu_indices: &[usize]) {
-    let Ok(topology) = Topology::new() else { return };
+    let Ok(topology) = Topology::new() else {
+        return;
+    };
     let mut cpuset = CpuSet::new();
     for &idx in cpu_indices {
         cpuset.set(idx);
@@ -85,8 +115,12 @@ pub fn pin_current_thread(cpu_indices: &[usize]) {
     let _ = topology.bind_cpu(&cpuset, CpuBindingFlags::THREAD);
 }
 
+#[cfg(not(feature = "numa"))]
+pub fn pin_current_thread(_cpu_indices: &[usize]) {}
+
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
+#[cfg(feature = "numa")]
 fn build_pool(cpus: &[usize]) -> Option<rayon::ThreadPool> {
     let cpus = cpus.to_vec();
     rayon::ThreadPoolBuilder::new()
@@ -103,7 +137,22 @@ fn build_pool(cpus: &[usize]) -> Option<rayon::ThreadPool> {
         .ok()
 }
 
-// ── PartitionRunner ───────────────────────────────────────────────────────────
+// ── PartitionRunner ─────────────────────────────────────────────────────────
+
+/// Growth step (fraction of a node's worker capacity added per activation
+/// event, see [`NodeActivation::grow`]).
+const GROWTH_DIVISOR: usize = 8;
+/// Minimum CPU efficiency growth to activate more workers, as a fraction of
+/// the size of the *last growth step* (e.g. `0.2` after adding 8 workers
+/// requires the next check to show at least +1.6 cores of growth — 20 % of
+/// the ~8 cores those 8 workers should contribute if the workload is truly
+/// CPU-bound). Scaling by the last step's size — not the cumulative total —
+/// keeps the bar meaningful regardless of how many workers are already
+/// active, instead of demanding an ever-larger absolute jump as the pool
+/// grows.
+const CPU_SPAWN_THRESHOLD: f64 = 0.2;
+/// Minimum I/O throughput growth (relative) to activate more workers.
+const IO_SPAWN_THRESHOLD: f64 = 0.2;
 
 struct NodeConfig {
     pool: Option<Arc<rayon::ThreadPool>>,
@@ -113,19 +162,24 @@ struct NodeConfig {
 
 /// Generic NUMA-aware runner for partition-level parallel work.
 ///
-/// Workers are distributed round-robin across NUMA nodes and pinned to their
+/// Workers are distributed evenly across NUMA nodes and pinned to their
-/// node's CPUs.  UMA systems are the degenerate case: one node, no pinning.
+/// node's CPUs. UMA is the degenerate case: one node, no pinning.
+///
+/// Workers are pre-spawned dormant, one activation channel per node so
+/// growth always targets a specific node rather than whichever dormant
+/// worker happens to wake up first on a shared channel. Growth (both the
+/// initial count and each subsequent step) is expressed as a fraction of
+/// `workers_per_node`, applied identically to every node, so the pace of
+/// ramp-up depends on node size rather than node count — a single-NUMA-node
+/// (UMA) machine ramps just as fast as an 8-node one.
 ///
 /// # Termination
 ///
-/// Termination is driven entirely by channel closure:
-///
 /// ```text
 /// drop(part_tx)      → part_rx drains → workers exit → drop their result_tx
 /// drop(result_tx)    → result_rx closes → controller loop exits
+/// drop(activate_txs) → dormant workers exit cleanly
 /// ```
-///
-/// No explicit counter or sentinel needed.
 pub struct PartitionRunner {
     nodes: Vec<NodeConfig>,
 }
@@ -136,111 +190,185 @@ impl PartitionRunner {
         self.nodes.iter().map(|n| n.max_workers).sum()
     }
 
-    /// Detect topology and build.  Falls back to a single-node UMA runner on
+    /// Detect topology and build. Always succeeds.
-    /// macOS, single-socket machines, or hwloc failure.
     pub fn new() -> Self {
-        match build() {
+        let ns = build();
-            Some(ns) => {
         let wpn = ns.workers_per_node();
         debug!(
-                    "PartitionRunner: NUMA mode — {} node(s) × {} worker(s)/node",
+            "PartitionRunner: {} node(s) × {} worker(s)/node max",
-                    ns.pools.len(), wpn,
+            ns.pools.len(),
+            wpn,
         );
-                let nodes = ns.pools
+        let nodes = ns
+            .pools
             .into_iter()
             .zip(ns.cpus_per_node)
             .map(|(pool, cpu_ids)| NodeConfig {
-                        pool:        Some(pool),
+                pool,
                 cpu_ids,
                 max_workers: wpn,
             })
             .collect();
         Self { nodes }
     }
-            None => {
-                let n_cores = std::thread::available_parallelism()
-                    .map(|n| n.get())
-                    .unwrap_or(1);
-                let max_workers = (n_cores / 2).max(1);
-                debug!("PartitionRunner: UMA mode — {} worker(s)", max_workers);
-                Self {
-                    nodes: vec![NodeConfig {
-                        pool:        None,
-                        cpu_ids:     vec![],
-                        max_workers,
-                    }],
-                }
-            }
-        }
-    }
 
     /// Run `f(i)` for every index in `order`.
     ///
-    /// Workers are spawned upfront and distributed round-robin across NUMA
+    /// Workers are pre-spawned dormant and activated adaptively, per node:
-    /// nodes.  `on_done(i, result, elapsed)` is called from the controller
+    /// `(workers_per_node / INITIAL_DIVISOR).max(1)` are woken immediately on
-    /// thread as each partition completes — suitable for progress bars and
+    /// every node, then `(workers_per_node / GROWTH_DIVISOR).max(1)` more per
-    /// result aggregation.
+    /// node each time the check below fires. A timer thread fires that check
+    /// every `TIMER_SECS` seconds; each completed partition resets that timer
+    /// (forcing an immediate check) and also triggers its own inline check. A
+    /// growth step happens whenever CPU efficiency grows by at least
+    /// `CPU_SPAWN_THRESHOLD` of what the last growth step should have
+    /// contributed, or I/O throughput grows by at least `IO_SPAWN_THRESHOLD`
+    /// (relative) since the last check — whichever resource is the actual
+    /// bottleneck still shows headroom.
+    ///
+    /// `on_done(i, result, elapsed)` is called from the controller thread as
+    /// each partition completes — suitable for progress bars and result
+    /// aggregation.
     ///
     /// Returns the first error produced by `f`, if any.
-    pub fn run<F, R, E, C>(
+    pub fn run<F, R, E, C>(&self, order: &[usize], f: F, mut on_done: C) -> Result<(), E>
-        &self,
-        order:      &[usize],
-        f:          F,
-        mut on_done: C,
-    ) -> Result<(), E>
     where
         F: Fn(usize) -> Result<R, E> + Send + Sync,
         R: Send,
         E: Send,
         C: FnMut(usize, R, Duration) + Send,
     {
-        // Pre-load the work queue, then drop the sender so workers' part_rx
+        let n_total = order.len();
-        // iterators terminate when the queue is drained.
+        if n_total == 0 {
+            return Ok(());
+        }
+
+        const TIMER_SECS: u64 = 30;
+        const INITIAL_DIVISOR: usize = 4;
+
+        // ── Channels ──────────────────────────────────────────────────────────
         let (part_tx, part_rx) = unbounded::<usize>();
-        for &i in order { part_tx.send(i).ok(); }
+        // reset_tx: controller → timer ("reset the 30 s window")
+        let (reset_tx, reset_rx) = unbounded::<()>();
+        // event_tx: workers + timer → controller (unified event stream)
+        let (event_tx, event_rx) = unbounded::<WorkerEvent<R, E>>();
+        // One activation channel per node: growth always targets a specific
+        // node, rather than whichever dormant worker happens to win the race
+        // on a channel shared across all nodes.
+        let (activate_txs, activate_rxs): (Vec<_>, Vec<_>) =
+            (0..self.nodes.len()).map(|_| unbounded::<()>()).unzip();
+
+        for &i in order {
+            part_tx.send(i).ok();
+        }
         drop(part_tx);
 
-        let (result_tx, result_rx) = unbounded::<(usize, Result<R, E>, Duration)>();
+        let max_workers = self.max_workers();
-        let n_nodes = self.nodes.len();
+        let node_caps: Vec<usize> = self.nodes.iter().map(|n| n.max_workers).collect();
-        let f = &f; // shared borrow; F: Sync so concurrent calls are safe
+        let f = &f;
 
         let mut first_err: Option<E> = None;
 
         std::thread::scope(|s| {
-            // Spawn all workers upfront, round-robin across NUMA nodes.
+            // ── Timer thread ──────────────────────────────────────────────────
-            for w in 0..self.max_workers() {
+            // Sends TimerTick every TIMER_SECS seconds. Resets its window each
-                let node    = &self.nodes[w % n_nodes];
+            // time reset_rx receives a message (i.e. on partition completion).
-                let prx     = part_rx.clone();
+            let timer_tx = event_tx.clone();
-                let rtx     = result_tx.clone();
+            s.spawn(move || {
-                let pool    = node.pool.clone();
+                let period = Duration::from_secs(TIMER_SECS);
+                loop {
+                    crossbeam_channel::select! {
+                        recv(reset_rx) -> r => {
+                            if r.is_err() { break; } // reset_tx dropped → exit
+                        }
+                        default(period) => {
+                            if timer_tx.send(WorkerEvent::TimerTick).is_err() { break; }
+                        }
+                    }
+                }
+            });
+
+            // ── Pre-spawn workers dormant, grouped by node ────────────────────
+            // Each worker listens on its own node's activation channel only.
+            for (node, arx) in self.nodes.iter().zip(activate_rxs.iter()) {
                 let cpu_ids = &node.cpu_ids;
+                for _ in 0..node.max_workers {
+                    let prx = part_rx.clone();
+                    let etx = event_tx.clone();
+                    let arx = arx.clone();
+                    let pool = node.pool.clone();
 
                     s.spawn(move || {
-                    if !cpu_ids.is_empty() { pin_current_thread(cpu_ids); }
+                        if arx.recv().is_err() {
+                            return;
+                        }
+                        if !cpu_ids.is_empty() {
+                            pin_current_thread(cpu_ids);
+                        }
                         for i in &prx {
                             let t = Instant::now();
                             let r = match &pool {
                                 Some(p) => p.install(|| f(i)),
                                 None => f(i),
                             };
-                        rtx.send((i, r, t.elapsed())).ok();
+                            etx.send(WorkerEvent::Completed(i, r, t.elapsed())).ok();
                         }
                     });
                 }
+            }
+            // Drop controller's event_tx: event_rx closes when all workers +
+            // timer have exited.
+            drop(event_tx);
 
-            // Drop the controller's sender: result_rx closes once all worker
+            // ── Controller ────────────────────────────────────────────────────
-            // rtx clones are dropped (i.e. all workers have exited).
+            let mut activation = NodeActivation::new(&activate_txs, &node_caps, max_workers);
-            drop(result_tx);
+            activation.activate_initial(INITIAL_DIVISOR, n_total);
 
-            // Drain results concurrently with workers.  The for loop exits
+            let mut cpu_sample = CpuSample::now();
-            // when result_rx is disconnected — at that point all workers are
+            let mut io_sample = IoSample::now();
-            // done and the scope join below is instantaneous.
+            let mut completed = 0usize;
-            for (i, r, dur) in &result_rx {
+
+            while completed < n_total {
+                let Ok(event) = event_rx.recv() else { break };
+                match event {
+                    WorkerEvent::Completed(i, r, dur) => {
                         match r {
                             Ok(v) => on_done(i, v, dur),
-                    Err(e) => { if first_err.is_none() { first_err = Some(e); } }
+                            Err(e) => {
+                                if first_err.is_none() {
+                                    first_err = Some(e);
                                 }
                             }
+                        }
+                        completed += 1;
+                        // Reset the 30 s timer.
+                        reset_tx.send(()).ok();
+                        // Inline check: same logic as a timer tick.
+                        maybe_activate(
+                            &mut activation,
+                            &mut cpu_sample,
+                            &mut io_sample,
+                            completed,
+                            n_total,
+                        );
+                    }
+                    WorkerEvent::TimerTick => {
+                        maybe_activate(
+                            &mut activation,
+                            &mut cpu_sample,
+                            &mut io_sample,
+                            completed,
+                            n_total,
+                        );
+                    }
+                }
+            }
+
+            // Dormant workers exit once every sender for their node's channel
+            // is dropped — `activate_txs` holds the only ones.
+            drop(activate_txs);
+            // Timer thread exits when reset_tx closes.
+            drop(reset_tx);
         });
 
         match first_err {
@@ -249,3 +377,121 @@ impl PartitionRunner {
         }
     }
 }
+
+// ── Internal event type ───────────────────────────────────────────────────────
+
+enum WorkerEvent<R, E> {
+    Completed(usize, Result<R, E>, Duration),
+    TimerTick,
+}
+
+/// Tracks how many of each node's dormant workers have been woken, and
+/// grows every node by the same amount at each step (capped by that node's
+/// remaining dormant workers and by the run's total budget) so load stays
+/// balanced across nodes at every point in time — never just "one more
+/// worker somewhere". Also remembers the size of the last real growth step
+/// (`last_step`), used to scale the CPU activation threshold to what that
+/// step could plausibly have contributed (see `maybe_activate`).
+struct NodeActivation<'a> {
+    txs: &'a [crossbeam_channel::Sender<()>],
+    caps: &'a [usize],
+    active: Vec<usize>,
+    total: usize,
+    max: usize,
+    last_step: usize,
+}
+
+impl<'a> NodeActivation<'a> {
+    fn new(txs: &'a [crossbeam_channel::Sender<()>], caps: &'a [usize], max: usize) -> Self {
+        Self {
+            txs,
+            caps,
+            active: vec![0; txs.len()],
+            total: 0,
+            max,
+            last_step: 0,
+        }
+    }
+
+    fn total(&self) -> usize {
+        self.total
+    }
+    fn last_step(&self) -> usize {
+        self.last_step
+    }
+    fn max(&self) -> usize {
+        self.max
+    }
+    fn is_full(&self) -> bool {
+        self.total >= self.max
+    }
+
+    /// Wake up to `(node_cap / divisor).max(1)` dormant workers on every
+    /// node, capped by `n_total`. Called once at startup, unconditionally.
+    fn activate_initial(&mut self, divisor: usize, n_total: usize) {
+        self.grow(divisor, n_total);
+    }
+
+    /// Same per-node sizing as [`activate_initial`](Self::activate_initial),
+    /// applied as a growth step. Returns the number of workers actually
+    /// activated (may be less than requested once a node or the total
+    /// budget is exhausted). Updates `last_step` when it actually grew.
+    fn grow(&mut self, divisor: usize, n_total: usize) -> usize {
+        let before = self.total;
+        for idx in 0..self.txs.len() {
+            let wanted = (self.caps[idx] / divisor).max(1);
+            let room = self.caps[idx].saturating_sub(self.active[idx]);
+            let grow = wanted.min(room).min(n_total.saturating_sub(self.total));
+            for _ in 0..grow {
+                self.txs[idx].send(()).ok();
+            }
+            self.active[idx] += grow;
+            self.total += grow;
+        }
+        let grew = self.total - before;
+        if grew > 0 {
+            self.last_step = grew;
+        }
+        grew
+    }
+}
+
+fn maybe_activate(
+    activation: &mut NodeActivation,
+    cpu_sample: &mut CpuSample,
+    io_sample: &mut IoSample,
+    completed: usize,
+    n_total: usize,
+) {
+    if activation.is_full() || completed >= n_total {
+        return;
+    }
+
+    // Expect roughly 1 core of extra efficiency per worker activated in the
+    // last growth step (CPU-bound case); require at least CPU_SPAWN_THRESHOLD
+    // (20 %) of that expected gain before growing again. Scaling by the last
+    // step's size — not the cumulative total — keeps the bar meaningful
+    // regardless of how many workers are already active: growing by 8 should
+    // always take ~+1.6 cores to confirm, whether that's the 2nd growth step
+    // or the 20th.
+    let cpu_threshold = CPU_SPAWN_THRESHOLD * activation.last_step() as f64;
+
+    // Call both unconditionally (no `||` short-circuit): each sampler must
+    // advance its own window every tick, regardless of what the other one
+    // reports, or it would starve behind whichever signal fires first.
+    let cpu_wants_more = cpu_sample.do_i_activate(cpu_threshold);
+    let io_wants_more = io_sample.do_i_activate(IO_SPAWN_THRESHOLD * activation.last_step() as f64);
+    if !(cpu_wants_more || io_wants_more) {
+        return;
+    }
+
+    let grew = activation.grow(GROWTH_DIVISOR, n_total);
+    if grew > 0 {
+        debug!(
+            "activated {} worker(s) — {}/{} active",
+            grew,
+            activation.total(),
+            activation.max()
+        );
+    }
+}

src/obikmer/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "obikmer"
-version = "1.1.6"
+version = "1.1.37"
 edition = "2024"
 
 [[bin]]
@@ -18,7 +18,7 @@ obikrope      = { path = "../obikrope" }
 obikpartitionner = { path = "../obikpartitionner" }
 obisys        = { path = "../obisys" }
 obiskio       = { path = "../obiskio" }
-obikindex     = { path = "../obikindex" }
+obikindex     = { path = "../obikindex", default-features = false }
 obitaxonomy   = { path = "../obitaxonomy" }
 obilayeredmap = { path = "../obilayeredmap" }
 clap          = { version = "4", features = ["derive"] }
@@ -33,4 +33,6 @@ tracing-subscriber = { version = "0.3", features = ["fmt", "env-filter"] }
 pprof = { version = "0.13", features = ["prost-codec"], optional = true }
 
 [features]
+default   = ["numa"]
+numa      = ["obikindex/numa"]
 profiling = ["dep:pprof"]

src/obikmer/src/cmd/query.rs

@@ -2,21 +2,26 @@ use std::collections::{HashMap, VecDeque};
 use std::io::{self, BufWriter, Write};
 use std::path::PathBuf;
 use std::sync::Arc;
+use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
+use std::time::Instant;
 
 use clap::Args;
 use obikindex::KmerIndex;
+use obikpartitionner::{KmerDesc, QueryHit, QueryStats};
 use obikrope::Rope;
-use obikseq::RoutableSuperKmer;
+use obikseq::CanonicalKmer;
 use obilayeredmap::IndexMode;
+use obipipeline::{Throttled, ThrottleGuard, throttle};
 use obiread::chunk::read_sequence_chunks_sized;
 use obiread::record::{SeqRecord, parse_chunk};
 use obiskbuilder::SuperKmerIter;
-use obisys::available_memory_bytes;
+use obisys::{Reporter, Stage, available_memory_bytes, spinner};
-use tracing::info;
+use tracing::{debug, info};
 
 // ── Pipeline data ─────────────────────────────────────────────────────────────
 
 enum QueryData {
+    Path(Throttled<PathBuf>),
     Chunk(Rope),
     Output(Vec<u8>),
 }
@@ -74,21 +79,34 @@ pub struct QueryArgs {
     /// I/O chunk size in MiB (default: auto-sized from available RAM and thread count)
     #[arg(long)]
     pub chunk_size: Option<usize>,
+
+    /// Maximum number of input files open simultaneously.
+    /// Defaults to threads/4 (minimum 1). Keep below the number of workers
+    /// to ensure CPU workers are always available for the transform stage.
+    #[arg(long)]
+    pub max_open_files: Option<usize>,
 }
 
-// ── SKDesc — one occurrence of a superkmer in the batch ───────────────────────
+impl QueryArgs {
-
+    pub fn effective_max_open(&self) -> usize {
-/// Describes one occurrence of a superkmer in the query batch.
+        self.max_open_files
-pub struct SKDesc {
+            .unwrap_or_else(|| (self.threads / 4).max(1))
-    /// Index of the source sequence within the batch.
+            .max(1)
-    pub seq_idx: u32,
+    }
-    /// Kmer offset of the first kmer of this superkmer within its sequence.
-    pub kmer_offset: u32,
 }
 
 // ── QueryBatch ────────────────────────────────────────────────────────────────
 
-/// A batch of query sequences with their superkmers deduplicated.
+/// A batch of query sequences, with k-mers deduplicated directly (not just at
+/// the superkmer level) and pre-split by partition.
+///
+/// Superkmer *construction* (`SuperKmerIter`) is still required — it's the
+/// mechanism that computes minimizers and partition routing — but the dedup
+/// key is the canonical k-mer, not the superkmer: two different superkmers
+/// that happen to share a k-mer (read overlaps, repeats, a SNP splitting an
+/// otherwise-identical run) are deduplicated too, not just identical whole
+/// superkmers. This also means each unique k-mer triggers at most one MPHF
+/// lookup, not one per occurrence.
 pub struct QueryBatch {
     /// Sequence ids in batch order.
     pub ids: Vec<String>,
@@ -96,30 +114,40 @@ pub struct QueryBatch {
     pub seqs: Vec<Vec<u8>>,
     /// Total kmer count per sequence (used for `--detail` coverage allocation).
     pub n_kmers: Vec<u32>,
-    /// Deduplicated superkmer map.
+    /// Deduplicated k-mer occurrences, one map per partition.
-    pub map: HashMap<RoutableSuperKmer, Vec<SKDesc>>,
+    pub by_partition: Vec<HashMap<CanonicalKmer, Vec<KmerDesc>>>,
 }
 
 impl QueryBatch {
-    /// Build a batch from a vec of parsed sequence records.
+    /// Build a batch from a vec of parsed sequence records, deduplicating
-    pub fn from_records(records: Vec<SeqRecord>, k: usize, level_max: usize, theta: f64) -> Self {
+    /// k-mers and routing them to partitions in the same pass.
+    pub fn from_records(
+        records: Vec<SeqRecord>,
+        k: usize,
+        level_max: usize,
+        theta: f64,
+        n_partitions: usize,
+    ) -> Self {
         let mut ids = Vec::with_capacity(records.len());
         let mut seqs = Vec::with_capacity(records.len());
         let mut n_kmers = Vec::with_capacity(records.len());
-        // Upper-bound estimate: at most one superkmer per k bases.
+        let mask = (n_partitions as u64) - 1;
-        // Avoids repeated rehash on large chunks.
+        let mut by_partition: Vec<HashMap<CanonicalKmer, Vec<KmerDesc>>> =
-        let cap = records.iter().map(|r| r.normalized.len()).sum::<usize>() / k.max(1);
+            (0..n_partitions).map(|_| HashMap::new()).collect();
-        let mut map: HashMap<RoutableSuperKmer, Vec<SKDesc>> = HashMap::with_capacity(cap);
 
         for (seq_idx, record) in records.into_iter().enumerate() {
             let mut kmer_offset = 0u32;
 
             for rsk in SuperKmerIter::new(&record.normalized, k, level_max, theta) {
-                let n = (rsk.seql() - k + 1) as u32;
+                let part_idx = (rsk.minimizer().seq_hash() & mask) as usize;
-                map.entry(rsk).or_default().push(SKDesc {
+                let map = &mut by_partition[part_idx];
+                for (j, kmer) in rsk.superkmer().iter_canonical_kmers().enumerate() {
+                    map.entry(kmer).or_default().push(KmerDesc {
                         seq_idx: seq_idx as u32,
-                    kmer_offset,
+                        pos: kmer_offset + j as u32,
                     });
+                }
+                let n = (rsk.seql() - k + 1) as u32;
                 kmer_offset += n;
             }
 
@@ -132,37 +160,27 @@ impl QueryBatch {
             ids,
             seqs,
             n_kmers,
-            map,
+            by_partition,
+        }
     }
 }
 
-    /// Split the superkmer map by partition index.
+// ── SmerIndex — sparse "was this k-mer found at all" bookkeeping ─────────────
-    pub fn split_by_partition(&self, n_partitions: usize) -> Vec<Vec<&RoutableSuperKmer>> {
+
-        let mask = (n_partitions as u64) - 1;
+/// Tracks, per (sequence, s-mer position), whether the k-mer was found in the
-        let mut by_part: Vec<Vec<&RoutableSuperKmer>> = vec![Vec::new(); n_partitions];
+/// index at all — independent of *which* genome(s) matched. Sized
-        for rsk in self.map.keys() {
+/// `total_smers` (one `bool` per s-mer occurrence in the chunk), **not**
-            let part = (rsk.minimizer().seq_hash() & mask) as usize;
+/// multiplied by `n_genomes`: this is the O(1)-per-position bookkeeping that
-            by_part[part].push(rsk);
+/// `kmer_missing` needs (the leftmost-s-mer-of-window membership test), kept
-        }
+/// dense because it's already cheap — the `n_genomes`-scaled data lives in
-        by_part
+/// the sparse per-genome hit lists built alongside it (see `process_chunk`).
-    }
+struct SmerIndex {
+    in_index: Vec<bool>, // total_smers
+    offsets: Vec<usize>, // offsets[i]..offsets[i+1] = s-mer range for sequence i
 }
 
-// ── KmerResults — allocation-free ragged result matrix ───────────────────────
+impl SmerIndex {
-
+    fn new(n_kmers_per_seq: &[u32]) -> Self {
-/// Flat storage for per-kmer query results across all sequences in a chunk.
-///
-/// Replaces `Vec<Vec<Option<Box<[u32]>>>>` — a single allocation for the whole
-/// chunk instead of one `Box<[u32]>` per found k-mer.
-struct KmerResults {
-    data: Vec<u32>,      // total_kmers × n_genomes, row-major
-    in_index: Vec<bool>, // total_kmers — true if the kmer was found in the index
-    offsets: Vec<usize>, // offsets[i]..offsets[i+1] = kmer range for sequence i
-    n_genomes: usize,
-}
-
-impl KmerResults {
-    fn new(n_kmers_per_seq: &[u32], n_genomes: usize) -> Self {
         let mut offsets = Vec::with_capacity(n_kmers_per_seq.len() + 1);
         let mut total = 0usize;
         offsets.push(0);
@@ -171,34 +189,96 @@ impl KmerResults {
             offsets.push(total);
         }
         Self {
-            data: vec![0u32; total * n_genomes],
             in_index: vec![false; total],
             offsets,
-            n_genomes,
         }
     }
 
-    fn n_kmers_for(&self, seq: usize) -> usize {
+    /// Mark the k-mer at (seq, kmer) as found in the index — independent of
-        self.offsets[seq + 1] - self.offsets[seq]
+    /// any particular genome's value. Called once per hit k-mer (stage 1 of
-    }
+    /// `query_partition_with`), regardless of how the column-major fetch
-
+    /// (stage 2) later reports per-genome values.
-    fn set(&mut self, seq: usize, kmer: usize, row: &[u32]) {
+    fn mark_found(&mut self, seq: usize, kmer: usize) {
         let abs = self.offsets[seq] + kmer;
         self.in_index[abs] = true;
-        let base = abs * self.n_genomes;
-        self.data[base..base + self.n_genomes].copy_from_slice(row);
     }
 
     #[inline]
     fn is_in_index(&self, seq: usize, kmer: usize) -> bool {
         self.in_index[self.offsets[seq] + kmer]
     }
-
-    /// Value for genome `g` at (seq, kmer); meaningful only when `is_in_index`.
-    #[inline]
-    fn val(&self, seq: usize, kmer: usize, g: usize) -> u32 {
-        self.data[(self.offsets[seq] + kmer) * self.n_genomes + g]
 }
+
+// ── Sparse Findere: per-genome run detection + sliding-window minimum ────────
+
+/// One confirmed z-window: genome `g`'s window ending at k-mer `pos` (the
+/// *leftmost* s-mer of the window, i.e. the k_user-mer's output position) is
+/// fully present and nonzero, with window-minimum `value`.
+type ConfirmedHit = (u32, u32, u32); // (seq_idx, pos_out, value)
+
+/// Reduce one genome's raw sparse s-mer hits — `(seq_idx, pos_smer, raw_value)`,
+/// unsorted, exactly as delivered by `QueryHit::Value` — into confirmed
+/// z-windows, without ever visiting a position that had no hit at all.
+///
+/// A z-window is confirmed only when all z s-mers in it are present *and*
+/// nonzero for this genome (matching the dense sliding-window's semantics,
+/// where "not in index" or a zero value both contribute 0 to the window
+/// minimum) — which can only happen inside a maximal run of consecutive
+/// `pos_smer` values for the same sequence. `hits` is sorted in place by
+/// `(seq_idx, pos_smer)` to expose those runs; the monotone-deque
+/// window-minimum then runs per run, on run-relative indices, identical in
+/// spirit to the dense version's whole-sequence scan.
+///
+/// Returns the confirmed hits plus `(n_runs, total_run_len)` for logging —
+/// a low average run length relative to `z` means most hits fail to form a
+/// complete window.
+fn sparse_findere_for_genome(
+    hits: &mut [(u32, u32, u32)],
+    z: usize,
+    presence: bool,
+    threshold: u32,
+) -> (Vec<ConfirmedHit>, usize, usize) {
+    hits.sort_unstable_by_key(|&(seq, pos, _)| (seq, pos));
+
+    let mut confirmed = Vec::new();
+    let mut n_runs = 0usize;
+    let mut total_run_len = 0usize;
+    let mut dq: VecDeque<(usize, u32)> = VecDeque::new(); // (run-relative index, value)
+
+    let mut i = 0;
+    while i < hits.len() {
+        let seq = hits[i].0;
+        let mut j = i + 1;
+        while j < hits.len() && hits[j].0 == seq && hits[j].1 == hits[j - 1].1 + 1 {
+            j += 1;
+        }
+        let run = &hits[i..j];
+        n_runs += 1;
+        total_run_len += run.len();
+
+        dq.clear();
+        for (k, &(_, pos, val)) in run.iter().enumerate() {
+            while dq.back().map_or(false, |&(_, v)| v >= val) {
+                dq.pop_back();
+            }
+            dq.push_back((k, val));
+            while dq.front().map_or(false, |&(fk, _)| fk + z <= k) {
+                dq.pop_front();
+            }
+            if k + 1 >= z {
+                let win_min = dq.front().unwrap().1;
+                if win_min > 0 {
+                    let pos_out = pos + 1 - z as u32;
+                    let c = if presence { u32::from(win_min >= threshold) } else { win_min };
+                    confirmed.push((seq, pos_out, c));
+                }
+            }
+        }
+
+        i = j;
+    }
+
+    (confirmed, n_runs, total_run_len)
 }
 
 // ── Per-sequence accumulator ──────────────────────────────────────────────────
@@ -234,40 +314,55 @@ fn process_chunk(
     force_presence: bool,
     presence_threshold: u32,
 ) -> Vec<u8> {
+    let chunk_start = Instant::now();
+    let chunk_bytes = rope.len();
+
     let records = parse_chunk(&rope, k);
     if records.is_empty() {
         return Vec::new();
     }
 
-    let batch = QueryBatch::from_records(records, k, 6, 0.7);
+    let batch = QueryBatch::from_records(records, k, 6, 0.7, n_partitions);
     let n_seqs = batch.ids.len();
 
-    // Flat result matrix — one allocation for the whole chunk.
+    // Sparse bookkeeping for the whole chunk:
-    let mut results = KmerResults::new(&batch.n_kmers, n_genomes);
+    // - smer_index: O(total_smers) — is this s-mer in the index at all.
+    // - by_genome[g]: raw (seq_idx, pos_smer, value) hits for genome g, only
+    //   ever containing nonzero entries (query_partition_with never emits a
+    //   QueryHit::Value for a zero value) — empty for every genome this chunk
+    //   never matched, which is the common case for unrelated queries.
+    let mut smer_index = SmerIndex::new(&batch.n_kmers);
+    let mut by_genome: Vec<Vec<(u32, u32, u32)>> = (0..n_genomes).map(|_| Vec::new()).collect();
 
-    let by_part = batch.split_by_partition(n_partitions);
+    // Dedup-ratio bookkeeping: occurrences (from batch.n_kmers, computed
+    // before dedup) vs. unique k-mers actually queried (query_stats) — the
+    // entire justification for k-mer-level dereplication (see query.md,
+    // Future work point 5). If this ratio stays close to 1.0 on real data,
+    // dereplication isn't paying for itself and that should show up here.
+    let n_occurrences: u64 = batch.n_kmers.iter().map(|&n| n as u64).sum();
+    let mut query_stats = QueryStats::default();
 
-    for (part_idx, part_sks) in by_part.iter().enumerate() {
+    for (part_idx, kmers) in batch.by_partition.iter().enumerate() {
-        if part_sks.is_empty() {
+        if kmers.is_empty() {
             continue;
         }
 
-        idx.partition()
+        let stats = idx.partition()
             .query_partition_with(
                 part_idx,
-                part_sks,
+                kmers,
-                k,
                 n_genomes,
                 with_counts,
-                |sk_idx, kmer_idx, row| {
+                |event| match event {
-                    let rsk = part_sks[sk_idx];
+                    QueryHit::Found(descs) => {
-                    let descs = batch.map.get(rsk).expect("rsk must be in map");
                         for desc in descs {
-                        results.set(
+                            smer_index.mark_found(desc.seq_idx as usize, desc.pos as usize);
-                            desc.seq_idx as usize,
+                        }
-                            desc.kmer_offset as usize + kmer_idx,
+                    }
-                            row,
+                    QueryHit::Value(descs, g, v) => {
-                        );
+                        for desc in descs {
+                            by_genome[g].push((desc.seq_idx, desc.pos, v));
+                        }
                     }
                 },
             )
@@ -275,96 +370,129 @@ fn process_chunk(
                 eprintln!("query error on partition {part_idx}: {e}");
                 std::process::exit(1);
             });
+        query_stats += stats;
     }
 
-    // Sliding window minimum — one reusable buffer and one deque per batch.
+    debug!(
-    //
+        n_occurrences,
-    // win_min[pos * n_genomes + g] = min count across the z-window [pos, pos+z)
+        n_unique_kmers = query_stats.n_unique_kmers,
-    // for genome g, where "not in index" counts as 0.
+        n_mphf_calls = query_stats.n_mphf_calls,
-    //
+        n_hits = query_stats.n_hits,
-    // win_min > 0  ↔  all z consecutive kmers are in the index with count > 0
+        n_columns_scanned = query_stats.n_columns_scanned,
-    //               ↔  Findere confirmation (for z=1 this degenerates to the
+        n_col_get_calls = query_stats.n_col_get_calls,
-    //                  simple case with no overhead).
+        "k-mer dedup + column-major fetch"
-    //
+    );
-    // Works uniformly for count matrices and presence/absence (0/1) matrices.
-    let max_n_kmers = batch.n_kmers.iter().map(|&n| n as usize).max().unwrap_or(0);
-    let mut win_min = vec![0u32; max_n_kmers * n_genomes];
 
-    let mut accs: Vec<SeqAcc> = (0..n_seqs).map(|_| SeqAcc::new(n_genomes)).collect();
+    // ── Sparse Findere: per-genome run detection + sliding-window minimum ────
+    //
+    // Confirmed z-windows, per genome, replace the dense win_min matrix:
+    // total retained memory is O(actual hits), not O(total_smers × n_genomes)
+    // — the whole point of this pass. See sparse_findere_for_genome's doc for
+    // why run detection is equivalent to the dense scan's semantics.
+    let presence  = force_presence || !with_counts;
+    let threshold = presence_threshold;
+    let z         = effective_z;
 
     let n_kmers_out: Vec<usize> = batch
         .n_kmers
         .iter()
         .map(|&n| {
             let n = n as usize;
-            if n >= effective_z { n - effective_z + 1 } else { 0 }
+            if n >= z { n - z + 1 } else { 0 }
         })
         .collect();
+    let mut out_offsets = Vec::with_capacity(n_seqs + 1);
+    {
+        let mut total = 0usize;
+        out_offsets.push(0);
+        for &n in &n_kmers_out {
+            total += n;
+            out_offsets.push(total);
+        }
+    }
+    let total_out = *out_offsets.last().unwrap_or(&0);
 
+    let n_dense_would_be = n_occurrences as u64 * n_genomes as u64;
+    let mut n_sparse_entries = 0u64;
+    let mut n_runs_total = 0usize;
+    let mut run_len_total = 0usize;
+
+    let mut confirmed_by_genome: Vec<Vec<ConfirmedHit>> = Vec::with_capacity(n_genomes);
+    for hits in &mut by_genome {
+        n_sparse_entries += hits.len() as u64;
+        let (confirmed, n_runs, run_len) = sparse_findere_for_genome(hits, z, presence, threshold);
+        n_runs_total += n_runs;
+        run_len_total += run_len;
+        confirmed_by_genome.push(confirmed);
+    }
+
+    debug!(
+        n_dense_would_be,
+        n_sparse_entries,
+        n_runs = n_runs_total,
+        avg_run_len = if n_runs_total > 0 { run_len_total as f64 / n_runs_total as f64 } else { 0.0 },
+        z,
+        "sparse Findere"
+    );
+
+    // Actual bytes retained by the sparse hit structures (by_genome +
+    // confirmed_by_genome, both alive simultaneously at this point — see the
+    // chunk-size formula's comment in `run()`), by allocated capacity rather
+    // than logical length so this reflects real memory pressure including
+    // Vec growth slack. `empirical_multiplier` is directly comparable to
+    // BYTES_PER_KMER_PER_GENOME (`run()`) — the ratio a cluster run's logs
+    // need to judge whether that constant is over- or under-conservative for
+    // real data, instead of guessing.
+    const HIT_ENTRY_BYTES: u64 = std::mem::size_of::<(u32, u32, u32)>() as u64;
+    let by_genome_bytes: u64 = by_genome.iter().map(|v| v.capacity() as u64 * HIT_ENTRY_BYTES).sum();
+    let confirmed_bytes: u64 = confirmed_by_genome.iter().map(|v| v.capacity() as u64 * HIT_ENTRY_BYTES).sum();
+    let retained_bytes = by_genome_bytes + confirmed_bytes;
+
+    debug!(
+        by_genome_bytes,
+        confirmed_bytes,
+        retained_bytes,
+        chunk_bytes,
+        empirical_multiplier = retained_bytes as f64 / chunk_bytes.max(1) as f64,
+        "sparse memory retained"
+    );
+
+    // ── Accumulate: genome totals (per genome, from confirmed hits) ──────────
+    let mut accs: Vec<SeqAcc> = (0..n_seqs).map(|_| SeqAcc::new(n_genomes)).collect();
+    let mut confirmed_any = vec![false; total_out];
+
+    for (g, hits) in confirmed_by_genome.iter().enumerate() {
+        for &(seq_idx, pos_out, c) in hits {
+            let abs_out = out_offsets[seq_idx as usize] + pos_out as usize;
+            confirmed_any[abs_out] = true;
+            accs[seq_idx as usize].genome_totals[g] += c;
+        }
+    }
+
+    // ── Accumulate: kmer_count / kmer_missing (per position, genome-independent) ─
+    for seq_idx in 0..n_seqs {
+        let out_n = n_kmers_out[seq_idx];
+        let acc = &mut accs[seq_idx];
+        for pos in 0..out_n {
+            let abs_out = out_offsets[seq_idx] + pos;
+            if confirmed_any[abs_out] {
+                acc.kmer_count += 1;
+            } else if !smer_index.is_in_index(seq_idx, pos) {
+                acc.kmer_missing += 1;
+            }
+        }
+    }
+
+    // ── Coverage (--detail): densify only when actually requested ────────────
     let mut cov: Vec<Vec<Vec<u32>>> = if detail {
         n_kmers_out.iter().map(|&n| vec![vec![0u32; n]; n_genomes]).collect()
     } else {
         Vec::new()
     };
-
+    if detail {
-    let presence  = force_presence || !with_counts;
+        for (g, hits) in confirmed_by_genome.iter().enumerate() {
-    let threshold = presence_threshold;
+            for &(seq_idx, pos_out, c) in hits {
-    let z         = effective_z;
+                cov[seq_idx as usize][g][pos_out as usize] += c;
-
-    // Deque reused across all (seq, genome) pairs.
-    let mut dq: VecDeque<(usize, u32)> = VecDeque::with_capacity(z + 1);
-
-    for seq_idx in 0..n_seqs {
-        let n     = results.n_kmers_for(seq_idx);
-        let out_n = n_kmers_out[seq_idx];
-        if out_n == 0 { continue; }
-
-        let mins = &mut win_min[..out_n * n_genomes];
-        mins.fill(0);
-
-        // ── Per-genome sliding window minimum ─────────────────────────────────
-        for g in 0..n_genomes {
-            dq.clear();
-            for i in 0..n {
-                let v_i = if results.is_in_index(seq_idx, i) {
-                    results.val(seq_idx, i, g)
-                } else {
-                    0
-                };
-                // Evict elements that have left the window.
-                while dq.front().map_or(false, |&(f, _)| f + z <= i) {
-                    dq.pop_front();
-                }
-                // Maintain monotone non-decreasing back→front for minimum at front.
-                while dq.back().map_or(false, |&(_, v)| v >= v_i) {
-                    dq.pop_back();
-                }
-                dq.push_back((i, v_i));
-                // Window [pos, pos+z) is complete when i = pos + z - 1.
-                if i + 1 >= z {
-                    let pos = i + 1 - z;
-                    mins[pos * n_genomes + g] = dq.front().unwrap().1;
-                }
-            }
-        }
-
-        // ── Accumulate ────────────────────────────────────────────────────────
-        let acc = &mut accs[seq_idx];
-        for pos in 0..out_n {
-            let any = (0..n_genomes).any(|g| mins[pos * n_genomes + g] > 0);
-            if !any {
-                if !results.is_in_index(seq_idx, pos) {
-                    acc.kmer_missing += 1;
-                }
-                continue;
-            }
-            acc.kmer_count += 1;
-            for g in 0..n_genomes {
-                let v = mins[pos * n_genomes + g];
-                if v == 0 { continue; }
-                let c = if presence { u32::from(v >= threshold) } else { v };
-                acc.genome_totals[g] += c;
-                if detail { cov[seq_idx][g][pos] += c; }
             }
         }
     }
@@ -384,9 +512,42 @@ fn process_chunk(
         &cov,
         &mut buf,
     );
+
+    debug!(
+        chunk_bytes,
+        n_seqs,
+        n_smers = batch.n_kmers.iter().map(|&n| n as u64).sum::<u64>(),
+        wall_ms = chunk_start.elapsed().as_millis() as u64,
+        "process_chunk"
+    );
+
     buf
 }
 
+// ── GuardedChunkIter — keeps the throttle slot guard alive until the file is exhausted ──
+
+/// Wraps a per-file `Rope` chunk iterator together with its `ThrottleGuard`,
+/// so the guard (and the throttle slot it holds) is only released once the
+/// file has been fully read — never earlier, never held past that point.
+struct GuardedChunkIter {
+    inner:      Box<dyn Iterator<Item = Rope> + Send>,
+    _guard:     ThrottleGuard,
+    files_open: Arc<AtomicU32>,
+}
+
+impl Iterator for GuardedChunkIter {
+    type Item = Rope;
+    fn next(&mut self) -> Option<Rope> {
+        self.inner.next()
+    }
+}
+
+impl Drop for GuardedChunkIter {
+    fn drop(&mut self) {
+        self.files_open.fetch_sub(1, Ordering::Relaxed);
+    }
+}
+
 // ── Entry point ───────────────────────────────────────────────────────────────
 
 pub fn run(args: QueryArgs) {
@@ -402,17 +563,67 @@ pub fn run(args: QueryArgs) {
     let n_workers = args.threads.max(1);
 
     // Chunk size: each chunk stays in memory for its entire processing lifetime.
-    // Overhead per raw byte is ~8× (Rope + parsed records + superkmers + results).
+    //
-    // We target ≤ 50 % of available RAM across all concurrent workers.
+    // Per-chunk memory is no longer a dense n_genomes-wide buffer (removed in
+    // the sparse Findere rework, see process_chunk) — it now scales with
+    // *actual hit count*, not with total_kmers_in_chunk × n_genomes
+    // unconditionally. BYTES_PER_KMER_PER_GENOME below is therefore a
+    // pathological-case bound, not a typical-case estimate: it protects
+    // against a fully-dense hit pattern (every k-mer of the query matching
+    // every genome — a degenerate case, e.g. low-complexity input theta-
+    // filtering should mostly reject, or an index of near-duplicate genomes),
+    // where by_genome and confirmed_by_genome (process_chunk) both end up
+    // holding one (seq_idx, pos, value) entry — 3 × u32 = 12 bytes, vs. 4
+    // bytes for the old dense encoding, where position was implicit in the
+    // array index — per (k-mer, genome) pair, and *coexist simultaneously*
+    // (by_genome isn't freed before confirmed_by_genome is built), for a
+    // worst case of ~24 bytes/pair before Vec growth slack. `cov` remains
+    // fully dense when --detail is set (unaffected by the sparse rework),
+    // still roughly doubling the n_genomes-scaled cost.
+    //
+    // For realistic, sparse hit patterns actual memory is far below this
+    // bound — see the "sparse memory retained" debug log in process_chunk,
+    // which reports the empirical bytes-per-raw-byte multiplier actually
+    // observed per chunk, directly comparable to BYTES_PER_KMER_PER_GENOME
+    // below. Tightening this constant for typical-case throughput (at the
+    // cost of pathological-case safety margin) is a deliberate tuning
+    // decision to make from that data, not something to guess at here.
+    //
+    // BASE_OVERHEAD approximates what scales with chunk_bytes alone,
+    // independent of n_genomes: the Rope itself, parsed SeqRecord sequence +
+    // normalised bytes, the superkmer dedup map, and the JSON output buffer.
+    // Like the n_genomes-scaled term, this is an estimate — validate against
+    // actual peak RSS (Stage::stop's `rss` in the summary table) on real
+    // workloads rather than trusting it blindly.
+    //
+    // We target ≤ 50 % of available RAM across all concurrent workers
+    // (SAFETY_FACTOR).
+    const BASE_OVERHEAD: u64 = 4;
+    const BYTES_PER_KMER_PER_GENOME: u64 = 8; // pathological-case bound — see comment above
+    const SAFETY_FACTOR: u64 = 2;
+
+    let detail_factor: u64 = if args.detail { 2 } else { 1 };
+    let overhead_multiplier =
+        BASE_OVERHEAD + n_genomes as u64 * BYTES_PER_KMER_PER_GENOME * detail_factor;
+
     let chunk_bytes = args
         .chunk_size
         .map(|mb| mb * 1024 * 1024)
         .unwrap_or_else(|| {
             let avail = available_memory_bytes();
-            let computed = avail / (n_workers as u64 * 16);
+            let computed = avail / (n_workers as u64 * overhead_multiplier * SAFETY_FACTOR);
             computed.clamp(4 * 1024 * 1024, 256 * 1024 * 1024) as usize
         });
 
+    debug!(
+        chunk_bytes,
+        n_genomes,
+        detail = args.detail,
+        overhead_multiplier,
+        estimated_peak_chunk_bytes = chunk_bytes as u64 * overhead_multiplier,
+        "chunk-size formula resolved"
+    );
+
     let effective_z: usize = args
         .findere_z
         .unwrap_or_else(|| match idx.meta().config.evidence {
@@ -435,48 +646,122 @@ pub fn run(args: QueryArgs) {
     let force_presence = args.force_presence;
     let presence_threshold = args.presence_threshold;
 
-    // Flat iterator over all Rope chunks from all input files.
+    // Throttled iterator over input file paths: at most `effective_max_open()`
-    // I/O runs in the source thread; chunk processing is parallelised by the pipe.
+    // files are open at once. Opening + decompressing + chunking each file is
-    info!("query: chunk_size={}MiB", chunk_bytes / (1024 * 1024));
+    // now a Flat pipeline stage, executed across the `n_workers` pool — not
+    // serialised in the pipe's dedicated source thread (see steps::scatter /
+    // cmd::superkmer for the same pattern applied to indexing).
+    info!("query: chunk_size={}MiB, max_open_files={}", chunk_bytes / (1024 * 1024), args.effective_max_open());
 
     let paths: Vec<PathBuf> = args.inputs.iter().map(PathBuf::from).collect();
-    let all_chunks = paths.into_iter().flat_map(move |path| {
+    let path_source = throttle(paths.into_iter(), args.effective_max_open());
-        let path_str = path.to_str().unwrap_or("").to_owned();
+
-        match read_sequence_chunks_sized(&path_str, chunk_bytes) {
+    // Instrumentation: total bytes processed (for the EMA throughput readout),
-            Ok(iter) => Box::new(iter.filter_map(|r| match r {
+    // number of files currently open/being chunked, and number of chunks
-                Ok(rope) => Some(rope),
+    // currently being processed by a worker — all read from the spinner loop
-                Err(e) => {
+    // below, updated from inside the pipe closures.
-                    eprintln!("read error: {e}");
+    let total_bytes = Arc::new(AtomicU64::new(0));
-                    None
+    let files_open = Arc::new(AtomicU32::new(0));
-                }
+    let chunks_active = Arc::new(AtomicU32::new(0));
-            })) as Box<dyn Iterator<Item = Rope> + Send>,
-            Err(e) => {
-                eprintln!("error opening {path_str}: {e}");
-                std::process::exit(1);
-            }
-        }
-    });
 
     let pipe = obipipeline::make_pipe! {
-        QueryData : Rope => Vec<u8>,
+        QueryData : Throttled<PathBuf> => Vec<u8>,
+        || {
+            let files_open = Arc::clone(&files_open);
+            move |pw: Throttled<PathBuf>| -> GuardedChunkIter {
+                let path = pw.item;
+                let guard = pw.guard;
+                let path_str = path.to_str().unwrap_or("").to_owned();
+                files_open.fetch_add(1, Ordering::Relaxed);
+                let open_start = Instant::now();
+                // Hard-exit on file-open failure (mirrors the previous behaviour):
+                // propagating this as a pipeline Err would hit a known scheduler
+                // hang on early stage errors (obipipeline::scheduler::WorkerPool::run
+                // breaks its main loop without unblocking the still-running source
+                // thread, so the final `h.join()` never returns) — worth fixing in
+                // obipipeline itself, but out of scope here; sidestepping it like the
+                // original code already did is the safe choice for this change.
+                let iter = read_sequence_chunks_sized(&path_str, chunk_bytes).unwrap_or_else(|e| {
+                    eprintln!("error opening {path_str}: {e}");
+                    std::process::exit(1);
+                });
+                debug!(
+                    path = %path_str,
+                    open_ms = open_start.elapsed().as_millis() as u64,
+                    "opened query input file"
+                );
+                let err_path = path_str.clone();
+                GuardedChunkIter {
+                    inner: Box::new(iter.filter_map(move |r| match r {
+                        Ok(rope) => Some(rope),
+                        Err(e) => {
+                            eprintln!("read error: {err_path}: {e}");
+                            None
+                        }
+                    })),
+                    _guard: guard,
+                    files_open: Arc::clone(&files_open),
+                }
+            }
+        } : Path => Chunk,
         | {
             let idx = Arc::clone(&idx);
+            let total_bytes = Arc::clone(&total_bytes);
+            let chunks_active = Arc::clone(&chunks_active);
             move |rope: Rope| {
-                process_chunk(
+                chunks_active.fetch_add(1, Ordering::Relaxed);
+                let bytes = rope.len() as u64;
+                let out = process_chunk(
                     &idx, rope, k, n_genomes, n_partitions, with_counts,
                     effective_z, detail, count_missing, force_presence, presence_threshold,
-                )
+                );
+                total_bytes.fetch_add(bytes, Ordering::Relaxed);
+                chunks_active.fetch_sub(1, Ordering::Relaxed);
+                out
             }
         } : Chunk => Output,
     };
 
+    let t = Stage::start("query");
+    let pb = spinner("query");
+
+    let mut ema_rate: f64 = 0.0;
+    let mut last_t = Instant::now();
+    let mut last_bytes: u64 = 0;
+    const ALPHA: f64 = 0.15;
+
     let mut out = BufWriter::new(io::stdout());
-    for block in pipe.apply(all_chunks, n_workers, 2) {
+    for block in pipe.apply(path_source, n_workers, 2) {
         if !block.is_empty() {
             out.write_all(&block).expect("write error");
         }
+
+        let now = Instant::now();
+        let dt = now.duration_since(last_t).as_secs_f64();
+        if dt > 0.1 {
+            let total = total_bytes.load(Ordering::Relaxed);
+            let instant = (total - last_bytes) as f64 / dt;
+            ema_rate = ALPHA * instant + (1.0 - ALPHA) * ema_rate;
+            last_t = now;
+            last_bytes = total;
+            let bp = total as f64;
+            let (count_str, rate_str) = if bp >= 1e9 {
+                (format!("{:.2} GB", bp / 1e9), format!("{:.0} MB/s", ema_rate / 1e6))
+            } else {
+                (format!("{:.0} MB", bp / 1e6), format!("{:.0} MB/s", ema_rate / 1e6))
+            };
+            let active = chunks_active.load(Ordering::Relaxed);
+            let open = files_open.load(Ordering::Relaxed);
+            pb.set_message(format!("{count_str}  {rate_str}  [files open: {open}, chunks in flight: {active}]"));
+        }
     }
     out.flush().expect("flush error");
+
+    pb.finish_and_clear();
+
+    let mut rep = Reporter::new();
+    rep.push(t.stop());
+    rep.print();
 }
 
 // ── Output ────────────────────────────────────────────────────────────────────
@@ -501,8 +786,10 @@ fn emit_batch(
 
         let mut match_map = serde_json::Map::new();
         for (g, genome) in meta.genomes.iter().enumerate() {
+            if acc.genome_totals[g] != 0 {
                 match_map.insert(genome.label.clone(), acc.genome_totals[g].into());
             }
+        }
         ann.insert("kmer_strict_matches".into(), match_map.into());
 
         if detail && !cov.is_empty() {
@@ -524,3 +811,7 @@ fn emit_batch(
         let _ = out.write_all(b"\n");
     }
 }
+
+#[cfg(test)]
+#[path = "tests/query.rs"]
+mod tests;

src/obikmer/src/cmd/tests/query.rs

@@ -0,0 +1,228 @@
+use super::*;
+
+const K: usize = 11;
+const M: usize = 5;
+
+/// Build a `QueryBatch` from raw FASTA text, going through the same
+/// `Rope` + `parse_chunk` path `process_chunk` uses — avoids hand-building a
+/// `normalized` `Rope`, which is an implementation detail of `obiread`.
+///
+/// `obikseq`'s global K/M params are thread-local under `test-utils` (see
+/// `obikseq::params`), so setting them here is per-test-thread and does not
+/// need coordination with other tests.
+fn batch_from_fasta(fasta: &str, k: usize, n_partitions: usize) -> QueryBatch {
+    obikseq::set_k(k);
+    obikseq::set_m(M);
+    let mut rope = Rope::new(Some("text/fasta"));
+    rope.push(fasta.as_bytes().to_vec());
+    let records = parse_chunk(&rope, k);
+    QueryBatch::from_records(records, k, 6, 0.7, n_partitions)
+}
+
+fn total_occurrences(batch: &QueryBatch) -> u64 {
+    batch.n_kmers.iter().map(|&n| n as u64).sum()
+}
+
+fn total_unique_kmers(batch: &QueryBatch) -> u64 {
+    batch.by_partition.iter().map(|m| m.len() as u64).sum()
+}
+
+// A 60 bp sequence, arbitrary but fixed — no attempt is made to prove it is
+// free of internal k=11 repeats; the tests below only rely on inequalities
+// that hold regardless (see each test's comment).
+const SEQ: &str = "CATTAGCGTACCTGATCAGGTTACAGCTTAGGCATCCAGTTGACCATGACTGGACTTAGC";
+
+#[test]
+fn single_sequence_yields_plausible_kmer_counts() {
+    // A single record can still contain internal repeats (SEQ isn't
+    // guaranteed repeat-free at k=11) — this only checks the batch is
+    // internally consistent, not a specific dedup ratio. The cross-record
+    // tests below make the actual, unconditional dedup claims.
+    let fasta = format!(">r1\n{SEQ}\n");
+    let batch = batch_from_fasta(&fasta, K, 1);
+
+    assert_eq!(batch.ids, vec!["r1".to_string()]);
+    let occurrences = total_occurrences(&batch);
+    let unique = total_unique_kmers(&batch);
+    assert!(occurrences > 0, "sequence should yield at least one k-mer");
+    assert!(unique > 0 && unique <= occurrences);
+}
+
+#[test]
+fn duplicated_sequence_across_records_deduplicates() {
+    // Two records with byte-identical sequences: every k-mer in record 1
+    // exactly duplicates one in record 0, so unique kmers <= n_kmers[0],
+    // strictly less than the summed occurrences (2 * n_kmers[0]) as long as
+    // the sequence yields at least one k-mer. This holds regardless of
+    // whether SEQ has internal repeats.
+    let fasta = format!(">r1\n{SEQ}\n>r2\n{SEQ}\n");
+    let batch = batch_from_fasta(&fasta, K, 1);
+
+    assert_eq!(batch.ids.len(), 2);
+    let occurrences = total_occurrences(&batch);
+    let unique = total_unique_kmers(&batch);
+
+    assert!(batch.n_kmers[0] > 0);
+    assert_eq!(occurrences, batch.n_kmers[0] as u64 + batch.n_kmers[1] as u64);
+    assert!(
+        unique <= batch.n_kmers[0] as u64,
+        "identical sequences must not produce more unique k-mers than one copy has"
+    );
+    assert!(
+        unique < occurrences,
+        "k-mer-level dedup must collapse at least the cross-record duplication"
+    );
+}
+
+#[test]
+fn duplicated_sequence_broadcasts_to_both_seq_indices() {
+    // Stronger than the ratio check above: pick any k-mer that hit in both
+    // records and confirm its occurrence list actually references both
+    // seq_idx 0 and seq_idx 1 — this is the specific new capability (dedup
+    // reaching across records/superkmers), not just a smaller unique count.
+    let fasta = format!(">r1\n{SEQ}\n>r2\n{SEQ}\n");
+    let batch = batch_from_fasta(&fasta, K, 1);
+
+    let shared = batch.by_partition[0]
+        .values()
+        .find(|descs| descs.iter().any(|d| d.seq_idx == 0) && descs.iter().any(|d| d.seq_idx == 1));
+
+    assert!(
+        shared.is_some(),
+        "expected at least one k-mer shared between the two identical records"
+    );
+}
+
+#[test]
+fn empty_records_yield_empty_batch() {
+    let batch = batch_from_fasta("", K, 1);
+    assert!(batch.ids.is_empty());
+    assert_eq!(total_occurrences(&batch), 0);
+    assert_eq!(total_unique_kmers(&batch), 0);
+}
+
+#[test]
+fn partition_routing_is_a_pure_function_of_the_kmer() {
+    // With n_partitions=4, every occurrence of a given k-mer must land in
+    // the same partition bucket as every other occurrence of that k-mer
+    // (partition routing is derived from the minimizer, shared by
+    // definition among instances of the same k-mer's containing superkmer
+    // in this test's single-sequence-pair setup).
+    let fasta = format!(">r1\n{SEQ}\n>r2\n{SEQ}\n");
+    let batch = batch_from_fasta(&fasta, K, 4);
+
+    let total_unique: u64 = batch.by_partition.iter().map(|m| m.len() as u64).sum();
+    assert!(total_unique > 0);
+
+    // No k-mer key appears in more than one partition's map.
+    let mut seen: std::collections::HashSet<CanonicalKmer> = std::collections::HashSet::new();
+    for map in &batch.by_partition {
+        for kmer in map.keys() {
+            assert!(seen.insert(*kmer), "k-mer routed to more than one partition");
+        }
+    }
+}
+
+// ── sparse_findere_for_genome vs. a dense reference implementation ──────────
+//
+// No property-testing crate (proptest/quickcheck) is a workspace dependency
+// (checked before writing this — not adding one for a single test module,
+// per this project's dependency-approval rule). A tiny deterministic xorshift
+// PRNG, std-only, stands in for one.
+
+/// Faithful reimplementation of the pre-phase-5 dense sliding-window scan —
+/// the algorithm `sparse_findere_for_genome` replaced — used here only as a
+/// correctness oracle, not in production code. Operates on one genome's
+/// hits across possibly many sequences, exactly like the sparse version.
+fn dense_reference_findere(
+    hits: &[(u32, u32, u32)],
+    seq_lens: &[usize],
+    z: usize,
+    presence: bool,
+    threshold: u32,
+) -> Vec<(u32, u32, u32)> {
+    let mut by_seq: Vec<Vec<u32>> = seq_lens.iter().map(|&n| vec![0u32; n]).collect();
+    for &(seq, pos, val) in hits {
+        by_seq[seq as usize][pos as usize] = val;
+    }
+
+    let mut confirmed = Vec::new();
+    for (seq_idx, values) in by_seq.iter().enumerate() {
+        let n = values.len();
+        let mut dq: std::collections::VecDeque<(usize, u32)> = std::collections::VecDeque::new();
+        for i in 0..n {
+            let v_i = values[i];
+            while dq.front().map_or(false, |&(f, _)| f + z <= i) {
+                dq.pop_front();
+            }
+            while dq.back().map_or(false, |&(_, v)| v >= v_i) {
+                dq.pop_back();
+            }
+            dq.push_back((i, v_i));
+            if i + 1 >= z {
+                let win_min = dq.front().unwrap().1;
+                if win_min > 0 {
+                    let pos_out = (i + 1 - z) as u32;
+                    let c = if presence { u32::from(win_min >= threshold) } else { win_min };
+                    confirmed.push((seq_idx as u32, pos_out, c));
+                }
+            }
+        }
+    }
+    confirmed
+}
+
+/// Minimal std-only xorshift64 PRNG — deterministic, seedable, no dependency.
+struct Xorshift64(u64);
+impl Xorshift64 {
+    fn next(&mut self) -> u64 {
+        self.0 ^= self.0 << 13;
+        self.0 ^= self.0 >> 7;
+        self.0 ^= self.0 << 17;
+        self.0
+    }
+    fn range(&mut self, n: u32) -> u32 {
+        (self.next() % n as u64) as u32
+    }
+}
+
+#[test]
+fn sparse_findere_matches_dense_reference_on_random_inputs() {
+    let mut rng = Xorshift64(0x5eed_5eed_5eed_5eedu64);
+
+    for case in 0..200 {
+        let n_seqs = 1 + rng.range(4) as usize;
+        let seq_lens: Vec<usize> = (0..n_seqs).map(|_| 1 + rng.range(30) as usize).collect();
+        let z = 1 + rng.range(4) as usize;
+        let presence = rng.range(2) == 0;
+        let threshold = 1 + rng.range(3);
+
+        // Sparse density varies across cases, including edge cases (empty,
+        // fully dense) — deliberately not uniform, to stress both few-hits
+        // and many-overlapping-runs scenarios.
+        let density = rng.range(101);
+        let mut hits: Vec<(u32, u32, u32)> = Vec::new();
+        for (seq_idx, &len) in seq_lens.iter().enumerate() {
+            for pos in 0..len {
+                if rng.range(100) < density {
+                    let val = 1 + rng.range(5); // never 0 — matches QueryHit::Value's invariant
+                    hits.push((seq_idx as u32, pos as u32, val));
+                }
+            }
+        }
+
+        let mut sparse_input = hits.clone();
+        let (mut sparse_result, _, _) =
+            sparse_findere_for_genome(&mut sparse_input, z, presence, threshold);
+        let mut dense_result = dense_reference_findere(&hits, &seq_lens, z, presence, threshold);
+
+        sparse_result.sort_unstable();
+        dense_result.sort_unstable();
+
+        assert_eq!(
+            sparse_result, dense_result,
+            "case {case}: n_seqs={n_seqs} seq_lens={seq_lens:?} z={z} presence={presence} \
+             threshold={threshold} density={density} hits={hits:?}"
+        );
+    }
+}

src/obikpartitionner/src/lib.rs

@@ -14,4 +14,5 @@ mod select_layer;
 pub use filter::{GroupQuorumFilter, KmerFilter, passes_all};
 pub use merge_layer::MergeMode;
 pub use partition::{KmerPartition, KmerSpectrum, PARTITIONS_SUBDIR};
+pub use query_layer::{KmerDesc, QueryHit, QueryStats};
 pub use select_layer::{AggOp, OutputCol};

src/obikpartitionner/src/query_layer.rs

@@ -1,7 +1,8 @@
+use std::collections::HashMap;
 use std::path::Path;
 
 use obicompactvec::{PersistentBitMatrix, PersistentCompactIntMatrix};
-use obikseq::{CanonicalKmer, RoutableSuperKmer};
+use obikseq::CanonicalKmer;
 use obiskio::{SKError, SKResult};
 use obilayeredmap::{IndexMode, MphfLayer, OLMError};
 use obilayeredmap::meta::PartitionMeta;
@@ -44,53 +45,133 @@ impl QueryLayer {
         }
     }
 
-    /// Write per-genome values into `buf` if `kmer` is indexed; returns true on hit.
+    /// MPHF lookup only — no matrix access. `Some(slot)` on hit.
-    fn find_into(&self, kmer: CanonicalKmer, n_genomes: usize, buf: &mut [u32]) -> bool {
+    fn find_slot(&self, kmer: CanonicalKmer) -> Option<usize> {
         match self {
-            QueryLayer::Presence(mphf, mat) => {
+            QueryLayer::Presence(mphf, _) | QueryLayer::Count(mphf, _) => mphf.find(kmer),
-                if let Some(slot) = mphf.find(kmer) {
-                    mat.fill_row(slot, &mut buf[..n_genomes]);
-                    true
-                } else {
-                    false
         }
     }
-            QueryLayer::Count(mphf, mat) => {
+
-                if let Some(slot) = mphf.find(kmer) {
+    /// Number of genome columns this layer's matrix actually has. Bounds
-                    mat.fill_row(slot, &mut buf[..n_genomes]);
+    /// column-major iteration — usually equal to the index's `n_genomes`, but
-                    true
+    /// `PersistentBitMatrix::Implicit` (the documented mono-genome fast path)
-                } else {
+    /// always reports exactly `1`, regardless of the index's real genome
-                    false
+    /// count, so callers must use this rather than assuming `n_genomes`.
+    fn n_cols(&self) -> usize {
+        match self {
+            QueryLayer::Presence(_, mat) => mat.n_cols(),
+            QueryLayer::Count(_, mat) => mat.n_cols(),
         }
     }
+
+    /// Column-major point lookup: value for genome column `g` at `slot`.
+    /// `g` must be `< self.n_cols()`; `slot` must come from [`find_slot`] on
+    /// this same layer.
+    fn col_value(&self, g: usize, slot: usize) -> u32 {
+        match self {
+            QueryLayer::Presence(_, mat) => mat.get(g, slot),
+            QueryLayer::Count(_, mat) => mat.col_view(g).get(slot),
         }
     }
 }
 
-// ── KmerPartition::query_partition* ──────────────────────────────────────────
+// ── KmerDesc — one occurrence of a k-mer in the query batch ──────────────────
+
+/// Describes one occurrence of a (deduplicated) k-mer in the query batch:
+/// which sequence it came from, and its absolute s-mer position within it.
+#[derive(Debug, Clone, Copy)]
+pub struct KmerDesc {
+    pub seq_idx: u32,
+    pub pos: u32,
+}
+
+/// Aggregate counters for one `query_partition_with` call — feeds the
+/// dedup-ratio and column-scan logging in `obikmer::cmd::query` (occurrences
+/// vs. unique k-mers is the whole justification for k-mer-level
+/// dereplication; columns scanned / `get()` calls quantify the column-major
+/// fetch's locality claim).
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct QueryStats {
+    /// Distinct canonical k-mers queried in this partition.
+    pub n_unique_kmers: usize,
+    /// Total `MphfLayer::find` calls issued (a k-mer tried against more than
+    /// one layer before a hit, or against all layers on a miss, counts once
+    /// per layer attempted).
+    pub n_mphf_calls: usize,
+    /// Distinct canonical k-mers that matched some layer.
+    pub n_hits: usize,
+    /// Total genome columns scanned across all hit layers (sum of
+    /// `layer.n_cols()` over layers with at least one hit).
+    pub n_columns_scanned: usize,
+    /// Total `col_value` calls issued during the column-major fetch pass
+    /// (`n_columns_scanned` × hits-per-layer, summed over layers).
+    pub n_col_get_calls: usize,
+}
+
+impl std::ops::AddAssign for QueryStats {
+    fn add_assign(&mut self, other: Self) {
+        self.n_unique_kmers += other.n_unique_kmers;
+        self.n_mphf_calls += other.n_mphf_calls;
+        self.n_hits += other.n_hits;
+        self.n_columns_scanned += other.n_columns_scanned;
+        self.n_col_get_calls += other.n_col_get_calls;
+    }
+}
+
+// ── QueryHit — one event delivered to query_partition_with's callback ───────
+
+/// One event from [`KmerPartition::query_partition_with`]'s two-stage query:
+/// a `Found` event once per hit k-mer (stage 1, MPHF-only — mark the k-mer as
+/// indexed regardless of any genome's value), then a `Value` event per
+/// `(hit k-mer, genome)` pair with a nonzero matrix value (stage 2,
+/// column-major fetch). Carried as one enum, not two separate callbacks, so
+/// the caller only needs one `FnMut` closure — passing two closures that each
+/// need to mutably borrow the same accumulator does not borrow-check.
+pub enum QueryHit<'a> {
+    Found(&'a [KmerDesc]),
+    Value(&'a [KmerDesc], usize, u32),
+}
+
+// ── KmerPartition::query_partition_with ──────────────────────────────────────
 
 impl KmerPartition {
-    /// Query a single partition, calling `on_hit(sk_idx, kmer_idx, row)` for
+    /// Query a single partition for a pre-deduplicated map of canonical
-    /// every found k-mer without allocating intermediate result vectors.
+    /// k-mers → their occurrences (`seq_idx`, `pos`) in the query batch.
+    ///
+    /// Two stages:
+    /// 1. **MPHF-only pass**: for each unique k-mer, try each layer's MPHF in
+    ///    turn (stopping at the first hit) and bucket confirmed hits by
+    ///    `(layer, slot)`. Emits one `QueryHit::Found` per hit k-mer. This
+    ///    stage's cost is independent of the index's genome count.
+    /// 2. **Column-major fetch**: for each layer with at least one hit, walk
+    ///    its matrix **column by column** (genome by genome) — for each
+    ///    genome, scan the slots bucketed in stage 1 and look up their value.
+    ///    Emits one `QueryHit::Value` per nonzero `(k-mer, genome)` pair.
+    ///    Total lookups are the same as a row-major pass (`n_hits × n_cols`
+    ///    in the worst case); the win is memory locality — both persistent
+    ///    matrix formats are column-oriented on disk (one `mmap`'d region per
+    ///    genome), so scanning one column at a time touches far fewer
+    ///    distinct mmap regions than fetching one full row per hit.
     pub fn query_partition_with<F>(
         &self,
         part_idx: usize,
-        superkmers: &[&RoutableSuperKmer],
+        kmers: &HashMap<CanonicalKmer, Vec<KmerDesc>>,
-        _k: usize,
         n_genomes: usize,
         with_counts: bool,
-        mut on_hit: F,
+        mut on_event: F,
-    ) -> SKResult<()>
+    ) -> SKResult<QueryStats>
     where
-        F: FnMut(usize, usize, &[u32]),
+        F: FnMut(QueryHit),
     {
-        if superkmers.is_empty() {
+        let mut stats = QueryStats::default();
-            return Ok(());
+
+        if kmers.is_empty() {
+            return Ok(stats);
         }
 
         let index_dir = self.part_dir(part_idx).join(INDEX_SUBDIR);
         if !index_dir.exists() {
-            return Ok(());
+            return Ok(stats);
         }
 
         let meta = PartitionMeta::load(&index_dir).map_err(olm_to_sk)?;
@@ -98,69 +179,47 @@ impl KmerPartition {
             .map(|i| QueryLayer::open(&index_dir.join(format!("layer_{i}")), with_counts, &meta.mode))
             .collect::<SKResult<_>>()?;
 
-        let mut buf = vec![0u32; n_genomes];
+        // ── Stage 1: MPHF-only pass, bucket hits by (layer_idx, slot) ────────
+        let mut by_layer: Vec<HashMap<usize, &Vec<KmerDesc>>> =
+            (0..layers.len()).map(|_| HashMap::new()).collect();
 
-        for (sk_idx, rsk) in superkmers.iter().enumerate() {
+        for (kmer, descs) in kmers {
-            for (kmer_idx, kmer) in rsk.superkmer().iter_canonical_kmers().enumerate() {
+            stats.n_unique_kmers += 1;
-                for layer in &layers {
+            for (layer_idx, layer) in layers.iter().enumerate() {
-                    if layer.find_into(kmer, n_genomes, &mut buf) {
+                stats.n_mphf_calls += 1;
-                        on_hit(sk_idx, kmer_idx, &buf);
+                if let Some(slot) = layer.find_slot(*kmer) {
-                        buf.fill(0);
+                    by_layer[layer_idx].insert(slot, descs);
+                    on_event(QueryHit::Found(descs));
+                    stats.n_hits += 1;
                     break;
                 }
             }
         }
+
+        // ── Stage 2: column-major fetch, per layer ───────────────────────────
+        for (layer_idx, slots) in by_layer.iter().enumerate() {
+            if slots.is_empty() {
+                continue;
+            }
+            let layer = &layers[layer_idx];
+            let n_cols = layer.n_cols().min(n_genomes);
+            stats.n_columns_scanned += n_cols;
+
+            for g in 0..n_cols {
+                for (&slot, descs) in slots {
+                    stats.n_col_get_calls += 1;
+                    let v = layer.col_value(g, slot);
+                    if v != 0 {
+                        on_event(QueryHit::Value(descs, g, v));
+                    }
+                }
+            }
         }
 
-        Ok(())
+        Ok(stats)
+    }
 }
 
-    /// Query a single partition for a slice of super-kmers, returning per-kmer rows.
+#[cfg(test)]
-    /// Prefer [`query_partition_with`] to avoid per-kmer heap allocations.
+#[path = "tests/query_layer.rs"]
-    pub fn query_partition(
+mod tests;
-        &self,
-        part_idx: usize,
-        superkmers: &[&RoutableSuperKmer],
-        _k: usize,
-        n_genomes: usize,
-        with_counts: bool,
-    ) -> SKResult<Vec<Vec<Option<Box<[u32]>>>>> {
-        if superkmers.is_empty() {
-            return Ok(Vec::new());
-        }
-
-        let index_dir = self.part_dir(part_idx).join(INDEX_SUBDIR);
-
-        if !index_dir.exists() {
-            return Ok(superkmers
-                .iter()
-                .map(|rsk| vec![None; rsk.seql()])
-                .collect());
-        }
-
-        let meta = PartitionMeta::load(&index_dir).map_err(olm_to_sk)?;
-        let layers: Vec<QueryLayer> = (0..meta.n_layers)
-            .map(|i| QueryLayer::open(&index_dir.join(format!("layer_{i}")), with_counts, &meta.mode))
-            .collect::<SKResult<_>>()?;
-
-        let mut buf = vec![0u32; n_genomes];
-        Ok(superkmers
-            .iter()
-            .map(|rsk| {
-                rsk.superkmer()
-                    .iter_canonical_kmers()
-                    .map(|kmer| {
-                        for layer in &layers {
-                            if layer.find_into(kmer, n_genomes, &mut buf) {
-                                let row: Box<[u32]> = buf[..n_genomes].into();
-                                buf.fill(0);
-                                return Some(row);
-                            }
-                        }
-                        None
-                    })
-                    .collect()
-            })
-            .collect())
-    }
-}

src/obikpartitionner/src/tests/query_layer.rs

@@ -0,0 +1,79 @@
+use super::*;
+
+// ── QueryStats::AddAssign ───────────────────────────────────────────────────
+
+#[test]
+fn query_stats_add_assign_sums_fields() {
+    let mut total = QueryStats {
+        n_unique_kmers: 3,
+        n_mphf_calls: 5,
+        n_hits: 2,
+        n_columns_scanned: 1,
+        n_col_get_calls: 7,
+    };
+    total += QueryStats {
+        n_unique_kmers: 1,
+        n_mphf_calls: 4,
+        n_hits: 1,
+        n_columns_scanned: 2,
+        n_col_get_calls: 3,
+    };
+    assert_eq!(total.n_unique_kmers, 4);
+    assert_eq!(total.n_mphf_calls, 9);
+    assert_eq!(total.n_hits, 3);
+    assert_eq!(total.n_columns_scanned, 3);
+    assert_eq!(total.n_col_get_calls, 10);
+}
+
+#[test]
+fn query_stats_default_is_zero() {
+    let s = QueryStats::default();
+    assert_eq!(s.n_unique_kmers, 0);
+    assert_eq!(s.n_mphf_calls, 0);
+    assert_eq!(s.n_hits, 0);
+    assert_eq!(s.n_columns_scanned, 0);
+    assert_eq!(s.n_col_get_calls, 0);
+}
+
+// ── query_partition_with on a not-yet-indexed partition ─────────────────────
+
+/// A `KmerPartition` created but never taken through `build_layers` has no
+/// `index/` subdirectory under any partition — `query_partition_with` must
+/// recognise this and return default (all-zero) stats rather than erroring,
+/// exactly like an empty `kmers` map.
+#[test]
+fn query_partition_with_missing_index_dir_returns_default_stats() {
+    let tmp = tempfile::tempdir().expect("tempdir");
+    let partition = KmerPartition::create(tmp.path().join("idx"), 2, 21, 9, false)
+        .expect("create partition");
+
+    let mut kmers: HashMap<CanonicalKmer, Vec<KmerDesc>> = HashMap::new();
+    // Any well-formed canonical k-mer works here — the call must return
+    // before ever attempting an MPHF lookup, since `index/` doesn't exist.
+    let kmer = CanonicalKmer::from_raw_unchecked(0u64);
+    kmers.insert(kmer, vec![KmerDesc { seq_idx: 0, pos: 0 }]);
+
+    let stats = partition
+        .query_partition_with(0, &kmers, 1, false, |_event| {
+            panic!("on_event must not be called: no index was built");
+        })
+        .expect("query_partition_with should not error on a missing index dir");
+
+    assert_eq!(stats, QueryStats::default());
+}
+
+#[test]
+fn query_partition_with_empty_kmers_is_a_noop() {
+    let tmp = tempfile::tempdir().expect("tempdir");
+    let partition = KmerPartition::create(tmp.path().join("idx"), 2, 21, 9, false)
+        .expect("create partition");
+
+    let kmers: HashMap<CanonicalKmer, Vec<KmerDesc>> = HashMap::new();
+    let stats = partition
+        .query_partition_with(0, &kmers, 1, false, |_event| {
+            panic!("on_event must not be called on an empty kmer map");
+        })
+        .expect("query_partition_with on an empty map should not error");
+
+    assert_eq!(stats, QueryStats::default());
+}

src/obilayeredmap/src/layered_store.rs

@@ -96,162 +96,5 @@ impl<S: BitPartials> BitPartials for LayeredStore<S> {
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
 #[cfg(test)]
-mod tests {
+#[path = "tests/layered_store.rs"]
-    use super::*;
+mod tests;
-    use obicompactvec::{
-        PersistentBitMatrix, PersistentBitMatrixBuilder,
-        PersistentCompactIntMatrix, PersistentCompactIntMatrixBuilder,
-    };
-    use tempfile::tempdir;
-
-    fn make_int_matrix(cols: &[&[u32]]) -> (tempfile::TempDir, PersistentCompactIntMatrix) {
-        let n = cols.first().map_or(0, |c| c.len());
-        let dir = tempdir().unwrap();
-        let mut b = PersistentCompactIntMatrixBuilder::new(n, &dir.path().join("counts")).unwrap();
-        for &col in cols {
-            let mut cb = b.add_col().unwrap();
-            for (slot, &v) in col.iter().enumerate() { cb.set(slot, v); }
-            cb.close().unwrap();
-        }
-        b.close().unwrap();
-        let m = PersistentCompactIntMatrix::open(dir.path()).unwrap();
-        (dir, m)
-    }
-
-    fn make_bit_matrix(cols: &[&[bool]]) -> (tempfile::TempDir, PersistentBitMatrix) {
-        let n = cols.first().map_or(0, |c| c.len());
-        let dir = tempdir().unwrap();
-        let mut b = PersistentBitMatrixBuilder::new(n, &dir.path().join("presence")).unwrap();
-        for &col in cols {
-            let mut cb = b.add_col().unwrap();
-            for (slot, &v) in col.iter().enumerate() { cb.set(slot, v); }
-            cb.close().unwrap();
-        }
-        b.close().unwrap();
-        let m = PersistentBitMatrix::open(dir.path()).unwrap();
-        (dir, m)
-    }
-
-    // ── ColumnWeights ─────────────────────────────────────────────────────────
-
-    #[test]
-    fn col_weights_sums_across_layers() {
-        // layer 0: col0=[1,2], col1=[3,4]   → weights [3, 7]
-        // layer 1: col0=[10,0], col1=[0,10]  → weights [10, 10]
-        // combined: [13, 17]
-        let (_d0, m0) = make_int_matrix(&[&[1, 2], &[3, 4]]);
-        let (_d1, m1) = make_int_matrix(&[&[10, 0], &[0, 10]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-        let w = store.col_weights();
-        assert_eq!(w[0], 13);
-        assert_eq!(w[1], 17);
-    }
-
-    #[test]
-    fn col_weights_bit_sums_across_layers() {
-        // layer 0: col0=[T,F,T], col1=[F,T,T]  → counts [2, 2]
-        // layer 1: col0=[F,F,T], col1=[T,T,F]  → counts [1, 2]
-        // combined: [3, 4]
-        let (_d0, m0) = make_bit_matrix(&[&[true, false, true], &[false, true, true]]);
-        let (_d1, m1) = make_bit_matrix(&[&[false, false, true], &[true, true, false]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-        let w = store.col_weights();
-        assert_eq!(w[0], 3);
-        assert_eq!(w[1], 4);
-    }
-
-    // ── CountPartials — layered (one partition) ───────────────────────────────
-
-    #[test]
-    fn layered_bray_matches_combined() {
-        // Split [1,2,3,4,5] across two layers; bray dist should equal direct computation
-        // on [1,2,3,4,5] for each column pair.
-        // col0=[1,2,3,4,5], col1=[5,4,3,2,1]
-        let (_d0, m0) = make_int_matrix(&[&[1, 2], &[5, 4]]);     // slots 0-1
-        let (_d1, m1) = make_int_matrix(&[&[3, 4, 5], &[3, 2, 1]]); // slots 2-4
-        let store = LayeredStore::new(vec![m0, m1]);
-
-        // direct on full data
-        let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
-        let expected = CountPartials::bray_dist_matrix(&mf);
-        let got      = CountPartials::bray_dist_matrix(&store);
-        assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "bray [0,1]");
-        assert!((got[[1, 0]] - expected[[1, 0]]).abs() < 1e-12, "bray [1,0]");
-    }
-
-    #[test]
-    fn layered_relfreq_bray_matches_combined() {
-        let (_d0, m0) = make_int_matrix(&[&[1, 2], &[5, 4]]);
-        let (_d1, m1) = make_int_matrix(&[&[3, 4, 5], &[3, 2, 1]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-
-        let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
-        let expected = CountPartials::relfreq_bray_dist_matrix(&mf);
-        let got      = CountPartials::relfreq_bray_dist_matrix(&store);
-        assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "relfreq_bray [0,1]");
-    }
-
-    #[test]
-    fn layered_euclidean_matches_combined() {
-        let (_d0, m0) = make_int_matrix(&[&[3, 0], &[0, 4]]);
-        let (_d1, m1) = make_int_matrix(&[&[1, 1], &[2, 2]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-
-        let (_df, mf) = make_int_matrix(&[&[3, 0, 1, 1], &[0, 4, 2, 2]]);
-        let expected = CountPartials::euclidean_dist_matrix(&mf);
-        let got      = CountPartials::euclidean_dist_matrix(&store);
-        assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "euclidean [0,1]");
-    }
-
-    // ── CountPartials — partitioned (LayeredStore<LayeredStore<_>>) ───────────
-
-    #[test]
-    fn partitioned_bray_matches_combined() {
-        // partition 0: slots [1,2,3,4,5]  col0 vs col1
-        // partition 1: slots [10,20]      col0 vs col1
-        let (_d0, p0) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
-        let (_d1, p1) = make_int_matrix(&[&[10, 20], &[20, 10]]);
-
-        let partitioned = LayeredStore::new(vec![
-            LayeredStore::new(vec![p0]),
-            LayeredStore::new(vec![p1]),
-        ]);
-
-        let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5, 10, 20], &[5, 4, 3, 2, 1, 20, 10]]);
-        let expected = CountPartials::bray_dist_matrix(&mf);
-        let got      = CountPartials::bray_dist_matrix(&partitioned);
-        assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "partitioned bray [0,1]");
-    }
-
-    // ── BitPartials ───────────────────────────────────────────────────────────
-
-    #[test]
-    fn layered_jaccard_matches_combined() {
-        let (_d0, m0) = make_bit_matrix(&[&[true, false], &[false, true]]);
-        let (_d1, m1) = make_bit_matrix(&[&[true, true], &[true, false]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-
-        let (_df, mf) = make_bit_matrix(&[
-            &[true, false, true, true],
-            &[false, true, true, false],
-        ]);
-        let expected = BitPartials::jaccard_dist_matrix(&mf);
-        let got      = BitPartials::jaccard_dist_matrix(&store);
-        assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "jaccard [0,1]");
-    }
-
-    #[test]
-    fn layered_hamming_matches_combined() {
-        let (_d0, m0) = make_bit_matrix(&[&[true, false], &[false, true]]);
-        let (_d1, m1) = make_bit_matrix(&[&[true, true], &[false, false]]);
-        let store = LayeredStore::new(vec![m0, m1]);
-
-        let (_df, mf) = make_bit_matrix(&[
-            &[true, false, true, true],
-            &[false, true, false, false],
-        ]);
-        let expected = BitPartials::hamming_dist_matrix(&mf);
-        let got      = BitPartials::hamming_dist_matrix(&store);
-        assert_eq!(got[[0, 1]], expected[[0, 1]], "hamming [0,1]");
-    }
-}

src/obilayeredmap/src/tests/layered_store.rs

@@ -0,0 +1,381 @@
+use super::*;
+use obicompactvec::{
+    PersistentBitMatrix, PersistentBitMatrixBuilder,
+    PersistentCompactIntMatrix, PersistentCompactIntMatrixBuilder,
+};
+use tempfile::tempdir;
+
+fn make_int_matrix(cols: &[&[u32]]) -> (tempfile::TempDir, PersistentCompactIntMatrix) {
+    let n = cols.first().map_or(0, |c| c.len());
+    let dir = tempdir().unwrap();
+    let mut b = PersistentCompactIntMatrixBuilder::new(n, &dir.path().join("counts")).unwrap();
+    for &col in cols {
+        let mut cb = b.add_col().unwrap();
+        for (slot, &v) in col.iter().enumerate() { cb.set(slot, v); }
+        cb.close().unwrap();
+    }
+    b.close().unwrap();
+    let m = PersistentCompactIntMatrix::open(dir.path()).unwrap();
+    (dir, m)
+}
+
+fn make_bit_matrix(cols: &[&[bool]]) -> (tempfile::TempDir, PersistentBitMatrix) {
+    let n = cols.first().map_or(0, |c| c.len());
+    let dir = tempdir().unwrap();
+    let mut b = PersistentBitMatrixBuilder::new(n, &dir.path().join("presence")).unwrap();
+    for &col in cols {
+        let mut cb = b.add_col().unwrap();
+        for (slot, &v) in col.iter().enumerate() { cb.set(slot, v); }
+        cb.close().unwrap();
+    }
+    b.close().unwrap();
+    let m = PersistentBitMatrix::open(dir.path()).unwrap();
+    (dir, m)
+}
+
+// ── ColumnWeights ─────────────────────────────────────────────────────────
+
+#[test]
+fn col_weights_sums_across_layers() {
+    // layer 0: col0=[1,2], col1=[3,4]   → weights [3, 7]
+    // layer 1: col0=[10,0], col1=[0,10]  → weights [10, 10]
+    // combined: [13, 17]
+    let (_d0, m0) = make_int_matrix(&[&[1, 2], &[3, 4]]);
+    let (_d1, m1) = make_int_matrix(&[&[10, 0], &[0, 10]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+    let w = store.col_weights();
+    assert_eq!(w[0], 13);
+    assert_eq!(w[1], 17);
+}
+
+#[test]
+fn col_weights_bit_sums_across_layers() {
+    // layer 0: col0=[T,F,T], col1=[F,T,T]  → counts [2, 2]
+    // layer 1: col0=[F,F,T], col1=[T,T,F]  → counts [1, 2]
+    // combined: [3, 4]
+    let (_d0, m0) = make_bit_matrix(&[&[true, false, true], &[false, true, true]]);
+    let (_d1, m1) = make_bit_matrix(&[&[false, false, true], &[true, true, false]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+    let w = store.col_weights();
+    assert_eq!(w[0], 3);
+    assert_eq!(w[1], 4);
+}
+
+// ── CountPartials — layered (one partition) ───────────────────────────────
+
+#[test]
+fn layered_bray_matches_combined() {
+    // Split [1,2,3,4,5] across two layers; bray dist should equal direct computation
+    // on [1,2,3,4,5] for each column pair.
+    // col0=[1,2,3,4,5], col1=[5,4,3,2,1]
+    let (_d0, m0) = make_int_matrix(&[&[1, 2], &[5, 4]]);     // slots 0-1
+    let (_d1, m1) = make_int_matrix(&[&[3, 4, 5], &[3, 2, 1]]); // slots 2-4
+    let store = LayeredStore::new(vec![m0, m1]);
+
+    // direct on full data
+    let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
+    let expected = CountPartials::bray_dist_matrix(&mf);
+    let got      = CountPartials::bray_dist_matrix(&store);
+    assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "bray [0,1]");
+    assert!((got[[1, 0]] - expected[[1, 0]]).abs() < 1e-12, "bray [1,0]");
+}
+
+#[test]
+fn layered_relfreq_bray_matches_combined() {
+    let (_d0, m0) = make_int_matrix(&[&[1, 2], &[5, 4]]);
+    let (_d1, m1) = make_int_matrix(&[&[3, 4, 5], &[3, 2, 1]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+
+    let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
+    let expected = CountPartials::relfreq_bray_dist_matrix(&mf);
+    let got      = CountPartials::relfreq_bray_dist_matrix(&store);
+    assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "relfreq_bray [0,1]");
+}
+
+#[test]
+fn layered_euclidean_matches_combined() {
+    let (_d0, m0) = make_int_matrix(&[&[3, 0], &[0, 4]]);
+    let (_d1, m1) = make_int_matrix(&[&[1, 1], &[2, 2]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+
+    let (_df, mf) = make_int_matrix(&[&[3, 0, 1, 1], &[0, 4, 2, 2]]);
+    let expected = CountPartials::euclidean_dist_matrix(&mf);
+    let got      = CountPartials::euclidean_dist_matrix(&store);
+    assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "euclidean [0,1]");
+}
+
+// ── CountPartials — partitioned (LayeredStore<LayeredStore<_>>) ───────────
+
+#[test]
+fn partitioned_bray_matches_combined() {
+    // partition 0: slots [1,2,3,4,5]  col0 vs col1
+    // partition 1: slots [10,20]      col0 vs col1
+    let (_d0, p0) = make_int_matrix(&[&[1, 2, 3, 4, 5], &[5, 4, 3, 2, 1]]);
+    let (_d1, p1) = make_int_matrix(&[&[10, 20], &[20, 10]]);
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0]),
+        LayeredStore::new(vec![p1]),
+    ]);
+
+    let (_df, mf) = make_int_matrix(&[&[1, 2, 3, 4, 5, 10, 20], &[5, 4, 3, 2, 1, 20, 10]]);
+    let expected = CountPartials::bray_dist_matrix(&mf);
+    let got      = CountPartials::bray_dist_matrix(&partitioned);
+    assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "partitioned bray [0,1]");
+}
+
+#[test]
+fn partitioned_threshold_jaccard_off_diagonal_is_pairwise() {
+    // 3 genomes, 2 partitions, 1 layer each — mirrors distance.rs's
+    // LayeredStore<LayeredStore<PersistentCompactIntMatrix>> shape.
+    // partition 0: col0=[3,0], col1=[0,3], col2=[3,3]
+    // partition 1: col0=[1,1], col1=[1,0], col2=[0,1]
+    let (_d0, p0) = make_int_matrix(&[&[3, 0], &[0, 3], &[3, 3]]);
+    let (_d1, p1) = make_int_matrix(&[&[1, 1], &[1, 0], &[0, 1]]);
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0]),
+        LayeredStore::new(vec![p1]),
+    ]);
+
+    let (_df, mf) = make_int_matrix(&[&[3, 0, 1, 1], &[0, 3, 1, 0], &[3, 3, 0, 1]]);
+    let threshold = 1u32;
+    let (inter_p, union_p) = CountPartials::partial_threshold_jaccard(&partitioned, threshold);
+    let (inter_f, union_f) = CountPartials::partial_threshold_jaccard(&mf, threshold);
+
+    let n = 3;
+    for i in 0..n {
+        for j in 0..n {
+            assert_eq!(inter_p[[i, j]], inter_f[[i, j]], "inter[{i},{j}]");
+            assert_eq!(union_p[[i, j]], union_f[[i, j]], "union[{i},{j}]");
+        }
+    }
+}
+
+#[test]
+fn partitioned_threshold_jaccard_packed_off_diagonal_is_pairwise() {
+    // Same as `partitioned_threshold_jaccard_off_diagonal_is_pairwise` but
+    // each partition matrix is packed into a single .pcmx file first —
+    // the on-disk format actually used in production after `pack_matrices`.
+    use obicompactvec::pack_compact_int_matrix;
+
+    let (d0, _p0) = make_int_matrix(&[&[3, 0], &[0, 3], &[3, 3]]);
+    pack_compact_int_matrix(&d0.path().join("counts")).unwrap();
+    let p0 = PersistentCompactIntMatrix::open(d0.path()).unwrap();
+
+    let (d1, _p1) = make_int_matrix(&[&[1, 1], &[1, 0], &[0, 1]]);
+    pack_compact_int_matrix(&d1.path().join("counts")).unwrap();
+    let p1 = PersistentCompactIntMatrix::open(d1.path()).unwrap();
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0]),
+        LayeredStore::new(vec![p1]),
+    ]);
+
+    let (_df, mf) = make_int_matrix(&[&[3, 0, 1, 1], &[0, 3, 1, 0], &[3, 3, 0, 1]]);
+    let threshold = 1u32;
+    let (inter_p, union_p) = CountPartials::partial_threshold_jaccard(&partitioned, threshold);
+    let (inter_f, union_f) = CountPartials::partial_threshold_jaccard(&mf, threshold);
+
+    let n = 3;
+    for i in 0..n {
+        for j in 0..n {
+            assert_eq!(inter_p[[i, j]], inter_f[[i, j]], "inter[{i},{j}]");
+            assert_eq!(union_p[[i, j]], union_f[[i, j]], "union[{i},{j}]");
+        }
+    }
+}
+
+#[test]
+fn partitioned_multilayer_threshold_jaccard_off_diagonal_is_pairwise() {
+    // 2 partitions, 2 layers each — the shape production indexes actually
+    // have (MPHF collision layers within a partition).
+    // partition 0, layer 0: col0=[3,0], col1=[0,3], col2=[3,3]
+    // partition 0, layer 1: col0=[2,0], col1=[0,0], col2=[2,0]
+    // partition 1, layer 0: col0=[1,1], col1=[1,0], col2=[0,1]
+    // partition 1, layer 1: col0=[0,5], col1=[5,5], col2=[0,0]
+    let (_d0a, p0a) = make_int_matrix(&[&[3, 0], &[0, 3], &[3, 3]]);
+    let (_d0b, p0b) = make_int_matrix(&[&[2, 0], &[0, 0], &[2, 0]]);
+    let (_d1a, p1a) = make_int_matrix(&[&[1, 1], &[1, 0], &[0, 1]]);
+    let (_d1b, p1b) = make_int_matrix(&[&[0, 5], &[5, 5], &[0, 0]]);
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0a, p0b]),
+        LayeredStore::new(vec![p1a, p1b]),
+    ]);
+
+    // Flattened equivalent: concatenate every layer's slots into one matrix.
+    let (_df, mf) = make_int_matrix(&[
+        &[3, 0, 2, 0, 1, 1, 0, 5],
+        &[0, 3, 0, 0, 1, 0, 5, 5],
+        &[3, 3, 2, 0, 0, 1, 0, 0],
+    ]);
+    let threshold = 1u32;
+    let (inter_p, union_p) = CountPartials::partial_threshold_jaccard(&partitioned, threshold);
+    let (inter_f, union_f) = CountPartials::partial_threshold_jaccard(&mf, threshold);
+
+    let n = 3;
+    for i in 0..n {
+        for j in 0..n {
+            assert_eq!(inter_p[[i, j]], inter_f[[i, j]], "inter[{i},{j}]");
+            assert_eq!(union_p[[i, j]], union_f[[i, j]], "union[{i},{j}]");
+        }
+    }
+}
+
+// ── BitPartials ───────────────────────────────────────────────────────────
+
+#[test]
+fn layered_jaccard_matches_combined() {
+    let (_d0, m0) = make_bit_matrix(&[&[true, false], &[false, true]]);
+    let (_d1, m1) = make_bit_matrix(&[&[true, true], &[true, false]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+
+    let (_df, mf) = make_bit_matrix(&[
+        &[true, false, true, true],
+        &[false, true, true, false],
+    ]);
+    let expected = BitPartials::jaccard_dist_matrix(&mf);
+    let got      = BitPartials::jaccard_dist_matrix(&store);
+    assert!((got[[0, 1]] - expected[[0, 1]]).abs() < 1e-12, "jaccard [0,1]");
+}
+
+#[test]
+fn layered_hamming_matches_combined() {
+    let (_d0, m0) = make_bit_matrix(&[&[true, false], &[false, true]]);
+    let (_d1, m1) = make_bit_matrix(&[&[true, true], &[false, false]]);
+    let store = LayeredStore::new(vec![m0, m1]);
+
+    let (_df, mf) = make_bit_matrix(&[
+        &[true, false, true, true],
+        &[false, true, false, false],
+    ]);
+    let expected = BitPartials::hamming_dist_matrix(&mf);
+    let got      = BitPartials::hamming_dist_matrix(&store);
+    assert_eq!(got[[0, 1]], expected[[0, 1]], "hamming [0,1]");
+}
+
+#[test]
+fn partitioned_bit_jaccard_off_diagonal_is_pairwise() {
+    // Same shape as the count-based `partitioned_multilayer_threshold_jaccard_*`
+    // tests, but for the presence/bit path (`with_counts = false` — what
+    // `all_specifics` actually uses in production).
+    // 4 genomes, 3 partitions, 2 layers in the last one.
+    let (_d0, p0) = make_bit_matrix(&[
+        &[true, false, true],
+        &[false, true, true],
+        &[true, true, false],
+        &[false, false, true],
+    ]);
+    let (_d1, p1) = make_bit_matrix(&[
+        &[true, true],
+        &[false, true],
+        &[true, false],
+        &[true, true],
+    ]);
+    let (_d2a, p2a) = make_bit_matrix(&[
+        &[false, true],
+        &[true, true],
+        &[false, false],
+        &[true, false],
+    ]);
+    let (_d2b, p2b) = make_bit_matrix(&[
+        &[true],
+        &[false],
+        &[true],
+        &[true],
+    ]);
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0]),
+        LayeredStore::new(vec![p1]),
+        LayeredStore::new(vec![p2a, p2b]),
+    ]);
+
+    // Flattened equivalent: concatenate every partition/layer's slots.
+    let (_df, mf) = make_bit_matrix(&[
+        &[true, false, true, true, true, false, true, true],
+        &[false, true, true, false, true, true, true, false],
+        &[true, true, false, true, false, false, false, true],
+        &[false, false, true, true, true, true, false, true],
+    ]);
+
+    let (inter_p, union_p) = BitPartials::partial_jaccard(&partitioned);
+    let (inter_f, union_f) = BitPartials::partial_jaccard(&mf);
+
+    let n = 4;
+    for i in 0..n {
+        for j in 0..n {
+            assert_eq!(inter_p[[i, j]], inter_f[[i, j]], "inter[{i},{j}]");
+            assert_eq!(union_p[[i, j]], union_f[[i, j]], "union[{i},{j}]");
+        }
+    }
+}
+
+#[test]
+fn partitioned_bit_jaccard_packed_off_diagonal_is_pairwise() {
+    // Same as `partitioned_bit_jaccard_off_diagonal_is_pairwise` but every
+    // partition's presence matrix is packed into a single .pbmx file —
+    // the on-disk format actually used in production after `pack_matrices`.
+    use obicompactvec::pack_bit_matrix;
+
+    let (d0, _p0) = make_bit_matrix(&[
+        &[true, false, true],
+        &[false, true, true],
+        &[true, true, false],
+        &[false, false, true],
+    ]);
+    pack_bit_matrix(&d0.path().join("presence")).unwrap();
+    let p0 = PersistentBitMatrix::open(d0.path()).unwrap();
+
+    let (d1, _p1) = make_bit_matrix(&[
+        &[true, true],
+        &[false, true],
+        &[true, false],
+        &[true, true],
+    ]);
+    pack_bit_matrix(&d1.path().join("presence")).unwrap();
+    let p1 = PersistentBitMatrix::open(d1.path()).unwrap();
+
+    let (d2a, _p2a) = make_bit_matrix(&[
+        &[false, true],
+        &[true, true],
+        &[false, false],
+        &[true, false],
+    ]);
+    pack_bit_matrix(&d2a.path().join("presence")).unwrap();
+    let p2a = PersistentBitMatrix::open(d2a.path()).unwrap();
+
+    let (d2b, _p2b) = make_bit_matrix(&[
+        &[true],
+        &[false],
+        &[true],
+        &[true],
+    ]);
+    pack_bit_matrix(&d2b.path().join("presence")).unwrap();
+    let p2b = PersistentBitMatrix::open(d2b.path()).unwrap();
+
+    let partitioned = LayeredStore::new(vec![
+        LayeredStore::new(vec![p0]),
+        LayeredStore::new(vec![p1]),
+        LayeredStore::new(vec![p2a, p2b]),
+    ]);
+
+    let (_df, mf) = make_bit_matrix(&[
+        &[true, false, true, true, true, false, true, true],
+        &[false, true, true, false, true, true, true, false],
+        &[true, true, false, true, false, false, false, true],
+        &[false, false, true, true, true, true, false, true],
+    ]);
+
+    let (inter_p, union_p) = BitPartials::partial_jaccard(&partitioned);
+    let (inter_f, union_f) = BitPartials::partial_jaccard(&mf);
+
+    let n = 4;
+    for i in 0..n {
+        for j in 0..n {
+            assert_eq!(inter_p[[i, j]], inter_f[[i, j]], "inter[{i},{j}]");
+            assert_eq!(union_p[[i, j]], union_f[[i, j]], "union[{i},{j}]");
+        }
+    }
+}

src/obisys/src/lib.rs

@@ -4,7 +4,7 @@ use std::sync::{Condvar, Mutex};
 use std::time::{Duration, Instant};
 
 use indicatif::{ProgressBar, ProgressStyle};
-use tracing::{info, warn};
+use tracing::{debug, info, warn};
 
 const BRAILLE: &[&str] = &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
@@ -31,7 +31,8 @@ impl TracedBar {
             let pct10 = (pos * 10) / self.total; // 0..=10
             let last = self.last_pct.load(Ordering::Relaxed);
             if pct10 > last
-                && self.last_pct
+                && self
+                    .last_pct
                     .compare_exchange(last, pct10, Ordering::Relaxed, Ordering::Relaxed)
                     .is_ok()
             {
@@ -49,14 +50,14 @@ impl TracedBar {
         let msg = msg.into();
         if self.pb.is_hidden() {
             if self.total > 0 {
-                // bounded bar: always log (already rate-limited by 10% threshold in inc)
+                debug!(stage = %self.label, "{msg}");
-                info!(stage = %self.label, "{msg}");
             } else {
                 // spinner: throttle to ~10 s
                 let now_ms = self.start.elapsed().as_millis() as u64;
                 let last = self.last_log_ms.load(Ordering::Relaxed);
                 if now_ms >= last + 10_000
-                    && self.last_log_ms
+                    && self
+                        .last_log_ms
                         .compare_exchange(last, now_ms, Ordering::Relaxed, Ordering::Relaxed)
                         .is_ok()
                 {
@@ -83,8 +84,13 @@ pub fn spinner(label: &str) -> TracedBar {
     );
     pb.enable_steady_tick(Duration::from_millis(100));
     TracedBar {
-        pb, label: label.to_string(), unit: String::new(), total: 0,
+        pb,
-        start: Instant::now(), last_pct: AtomicU64::new(0), last_log_ms: AtomicU64::new(0),
+        label: label.to_string(),
+        unit: String::new(),
+        total: 0,
+        start: Instant::now(),
+        last_pct: AtomicU64::new(0),
+        last_log_ms: AtomicU64::new(0),
     }
 }
 
@@ -101,8 +107,13 @@ pub fn progress_bar(label: &str, n: u64, unit: &str) -> TracedBar {
     );
     pb.enable_steady_tick(Duration::from_millis(100));
     TracedBar {
-        pb, label: label.to_string(), unit: unit.to_string(), total: n,
+        pb,
-        start: Instant::now(), last_pct: AtomicU64::new(0), last_log_ms: AtomicU64::new(0),
+        label: label.to_string(),
+        unit: unit.to_string(),
+        total: n,
+        start: Instant::now(),
+        last_pct: AtomicU64::new(0),
+        last_log_ms: AtomicU64::new(0),
     }
 }
 
@@ -204,13 +215,19 @@ fn tv_to_secs(tv: timeval) -> f64 {
 }
 
 #[cfg(target_os = "macos")]
-fn rss_to_bytes(ru: &rusage) -> u64 { ru.ru_maxrss as u64 }
+fn rss_to_bytes(ru: &rusage) -> u64 {
+    ru.ru_maxrss as u64
+}
 
 #[cfg(not(target_os = "macos"))]
-fn rss_to_bytes(ru: &rusage) -> u64 { ru.ru_maxrss as u64 * 1024 }
+fn rss_to_bytes(ru: &rusage) -> u64 {
+    ru.ru_maxrss as u64 * 1024
+}
 
 // Monotonically increasing counters — negative delta would be a kernel bug.
-fn delta(end: i64, start: i64) -> u64 { (end - start).max(0) as u64 }
+fn delta(end: i64, start: i64) -> u64 {
+    (end - start).max(0) as u64
+}
 
 // ── CpuSample ─────────────────────────────────────────────────────────────────
 
@@ -221,6 +238,7 @@ pub struct CpuSample {
     wall: Instant,
     user_secs: f64,
     sys_secs: f64,
+    previous: f64,
 }
 
 impl CpuSample {
@@ -230,6 +248,7 @@ impl CpuSample {
             wall: Instant::now(),
             user_secs: tv_to_secs(ru.ru_utime),
             sys_secs: tv_to_secs(ru.ru_stime),
+            previous: 0.0,
         }
     }
 
@@ -238,11 +257,129 @@ impl CpuSample {
     pub fn cpu_efficiency(&self, n_cores: usize) -> f64 {
         let ru = get_rusage();
         let wall = self.wall.elapsed().as_secs_f64();
-        if wall < 0.1 { return 0.0; }
+        if wall < 0.1 {
-        let cpu = (tv_to_secs(ru.ru_utime) - self.user_secs)
+            return 0.0;
-                + (tv_to_secs(ru.ru_stime) - self.sys_secs);
+        }
+        let cpu =
+            (tv_to_secs(ru.ru_utime) - self.user_secs) + (tv_to_secs(ru.ru_stime) - self.sys_secs);
         cpu / (wall * n_cores as f64)
     }
+
+    pub fn do_i_activate(&mut self, threshold: f64) -> bool {
+        let delta_wall = self.wall.elapsed().as_secs_f64();
+        if delta_wall < 0.1 {
+            // Window too short to be meaningful — leave state untouched so it
+            // keeps accumulating until a real sample can be taken.
+            return false;
+        }
+
+        let n = CpuSample::now();
+        let delta_ru = (n.user_secs - self.user_secs) + (n.sys_secs - self.sys_secs);
+
+        let efficiency = delta_ru / delta_wall;
+        let activate = 0f64.max(efficiency - self.previous) >= threshold;
+
+        debug!(
+            "Do I activate : {} -> {} = {} Activate: {}",
+            self.previous,
+            efficiency,
+            0f64.max(efficiency - self.previous),
+            activate
+        );
+        self.previous = efficiency;
+        self.user_secs = n.user_secs;
+        self.sys_secs = n.sys_secs;
+        self.wall = n.wall;
+
+        activate
+    }
+}
+
+// ── IoSample ──────────────────────────────────────────────────────────────────
+
+/// Snapshot of process-wide block I/O (bytes read + written) + wall clock.
+///
+/// Same activation protocol as [`CpuSample`], but the growth check in
+/// [`do_i_activate`](Self::do_i_activate) is *relative* rather than absolute:
+/// raw I/O throughput has no portable scale across storage devices, unlike a
+/// core count.
+pub struct IoSample {
+    wall: Instant,
+    bytes: u64,
+    previous_rate: f64,
+}
+
+impl IoSample {
+    pub fn now() -> Self {
+        Self {
+            wall: Instant::now(),
+            bytes: Self::read_bytes(),
+            previous_rate: 0.0,
+        }
+    }
+
+    /// Bytes actually submitted to the block layer (read + write), summed
+    /// process-wide. Returns 0 if unavailable — degrades gracefully to a
+    /// signal that never triggers activation (CPU-only heuristic).
+    #[cfg(target_os = "linux")]
+    fn read_bytes() -> u64 {
+        let Ok(io) = std::fs::read_to_string("/proc/self/io") else {
+            return 0;
+        };
+        io.lines()
+            .filter_map(|l| {
+                l.strip_prefix("read_bytes: ")
+                    .or_else(|| l.strip_prefix("write_bytes: "))
+            })
+            .filter_map(|v| v.trim().parse::<u64>().ok())
+            .sum()
+    }
+
+    #[cfg(target_os = "macos")]
+    fn read_bytes() -> u64 {
+        use libc::{RUSAGE_INFO_V4, getpid, proc_pid_rusage, rusage_info_v4};
+        let mut info: rusage_info_v4 = unsafe { std::mem::zeroed() };
+        let ret =
+            unsafe { proc_pid_rusage(getpid(), RUSAGE_INFO_V4, &mut info as *mut _ as *mut _) };
+        if ret != 0 {
+            return 0;
+        }
+        info.ri_diskio_bytesread + info.ri_diskio_byteswritten
+    }
+
+    #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+    fn read_bytes() -> u64 {
+        0
+    }
+
+    /// Same protocol as [`CpuSample::do_i_activate`] (0.1 s minimum window,
+    /// state untouched on early return), but growth is measured relative to
+    /// the previous rate. `threshold` is a fraction, e.g. `0.2` for a 20 %
+    /// increase in throughput since the last real sample.
+    pub fn do_i_activate(&mut self, threshold: f64) -> bool {
+        let elapsed = self.wall.elapsed().as_secs_f64();
+        if elapsed < 0.1 {
+            return false;
+        }
+
+        let n = Self::read_bytes();
+        let rate = n.saturating_sub(self.bytes) as f64 / elapsed;
+        let activate = if self.previous_rate == 0.0 {
+            rate > 0.0 // bootstrap: any measured throughput is signal enough
+        } else {
+            (rate - self.previous_rate) / self.previous_rate >= threshold
+        };
+
+        debug!(
+            "Do I activate (I/O) : {} -> {} Activate: {}",
+            self.previous_rate, rate, activate
+        );
+        self.previous_rate = rate;
+        self.bytes = n;
+        self.wall = Instant::now();
+
+        activate
+    }
 }
 
 // ── public API ────────────────────────────────────────────────────────────────
@@ -259,7 +396,11 @@ impl Stage {
     pub fn start(label: impl Into<String>) -> Self {
         let label = label.into();
         info!(stage = %label, "started");
-        Self { label, wall: Instant::now(), ru: get_rusage() }
+        Self {
+            label,
+            wall: Instant::now(),
+            ru: get_rusage(),
+        }
     }
 
     pub fn stop(self) -> StageStats {
@@ -318,8 +459,11 @@ pub struct StageStats {
 impl StageStats {
     /// (user + sys) / wall — effective thread count utilisation.
     pub fn parallelism(&self) -> f64 {
-        if self.wall_secs > 1e-9 { (self.user_secs + self.sys_secs) / self.wall_secs }
+        if self.wall_secs > 1e-9 {
-        else { 0.0 }
+            (self.user_secs + self.sys_secs) / self.wall_secs
+        } else {
+            0.0
+        }
     }
 
     /// parallelism / n_cores — fraction of available CPU power used (0..1+).
@@ -335,11 +479,19 @@ pub struct Reporter {
 }
 
 impl Reporter {
-    pub fn new() -> Self { Self::default() }
+    pub fn new() -> Self {
-    pub fn push(&mut self, stats: StageStats) { self.stages.push(stats); }
+        Self::default()
-    pub fn stages(&self) -> &[StageStats] { &self.stages }
+    }
+    pub fn push(&mut self, stats: StageStats) {
+        self.stages.push(stats);
+    }
+    pub fn stages(&self) -> &[StageStats] {
+        &self.stages
+    }
     /// Print the summary to stderr.
-    pub fn print(&self) { eprint!("{self}"); }
+    pub fn print(&self) {
+        eprint!("{self}");
+    }
 }
 
 // ── diagnosis ─────────────────────────────────────────────────────────────────
@@ -387,26 +539,43 @@ fn diagnose(s: &StageStats, n_cores: usize) -> Diagnosis {
             )),
         };
     }
-    Diagnosis { tag: "—", detail: None }
+    Diagnosis {
+        tag: "—",
+        detail: None,
+    }
 }
 
 // ── display helpers ───────────────────────────────────────────────────────────
 
 fn fmt_secs(s: f64) -> String {
-    if s >= 100.0     { format!("{:.0}s",  s) }
+    if s >= 100.0 {
-    else if s >= 10.0 { format!("{:.1}s",  s) }
+        format!("{:.0}s", s)
-    else if s >= 1.0  { format!("{:.2}s",  s) }
+    } else if s >= 10.0 {
-    else              { format!("{:.0}ms", s * 1000.0) }
+        format!("{:.1}s", s)
+    } else if s >= 1.0 {
+        format!("{:.2}s", s)
+    } else {
+        format!("{:.0}ms", s * 1000.0)
+    }
 }
 
 fn fmt_bytes(b: u64) -> String {
-    if b >= 1 << 30      { format!("{:.1} GB", b as f64 / (1u64 << 30) as f64) }
+    if b >= 1 << 30 {
-    else if b >= 1 << 20 { format!("{:.0} MB", b as f64 / (1u64 << 20) as f64) }
+        format!("{:.1} GB", b as f64 / (1u64 << 30) as f64)
-    else                 { format!("{:.0} KB", b as f64 / 1024.0) }
+    } else if b >= 1 << 20 {
+        format!("{:.0} MB", b as f64 / (1u64 << 20) as f64)
+    } else {
+        format!("{:.0} KB", b as f64 / 1024.0)
+    }
 }
 
 fn fmt_efficiency(par: f64, n_cores: usize) -> String {
-    format!("{:.1}×/{} ({:.0}%)", par, n_cores, par / n_cores as f64 * 100.0)
+    format!(
+        "{:.1}×/{} ({:.0}%)",
+        par,
+        n_cores,
+        par / n_cores as f64 * 100.0
+    )
 }
 
 // ── Display ───────────────────────────────────────────────────────────────────
@@ -434,7 +603,11 @@ impl MemoryBudget {
     pub fn new(total: u64) -> Self {
         Self {
             total,
-            inner:   Mutex::new(BudgetInner { remaining: total, active: 0, peak_active: 0 }),
+            inner: Mutex::new(BudgetInner {
+                remaining: total,
+                active: 0,
+                peak_active: 0,
+            }),
             condvar: Condvar::new(),
         }
     }
@@ -459,24 +632,40 @@ impl MemoryBudget {
         self.condvar.notify_all();
     }
 
-    pub fn total(&self)       -> u64   { self.total }
+    pub fn total(&self) -> u64 {
-    pub fn active(&self)      -> usize { self.inner.lock().unwrap().active }
+        self.total
-    pub fn remaining(&self)   -> u64   { self.inner.lock().unwrap().remaining }
+    }
-    pub fn peak_active(&self) -> usize { self.inner.lock().unwrap().peak_active }
+    pub fn active(&self) -> usize {
+        self.inner.lock().unwrap().active
+    }
+    pub fn remaining(&self) -> u64 {
+        self.inner.lock().unwrap().remaining
+    }
+    pub fn peak_active(&self) -> usize {
+        self.inner.lock().unwrap().peak_active
+    }
 }
 
 // ── Display ───────────────────────────────────────────────────────────────────
 
 impl fmt::Display for Reporter {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        if self.stages.is_empty() { return Ok(()); }
+        if self.stages.is_empty() {
+            return Ok(());
+        }
 
         let n_cores = std::thread::available_parallelism()
             .map(|n| n.get())
             .unwrap_or(1);
 
         // column widths
-        let nw = self.stages.iter().map(|s| s.label.len()).max().unwrap_or(5).max(5);
+        let nw = self
+            .stages
+            .iter()
+            .map(|s| s.label.len())
+            .max()
+            .unwrap_or(5)
+            .max(5);
         // efficiency col: worst-case width for this run's n_cores value
         let ew = format!("{:.1}×/{} (100%)", 99.9f64, n_cores).len();
 
@@ -484,18 +673,21 @@ impl fmt::Display for Reporter {
         let sep = "─".repeat(sep_w);
 
         // header
-        writeln!(f, "{:<nw$}  {:>7}  {:>ew$}  {:>8}  status",
+        writeln!(
-            "stage", "wall", "efficiency", "peak RSS")?;
+            f,
+            "{:<nw$}  {:>7}  {:>ew$}  {:>8}  status",
+            "stage", "wall", "efficiency", "peak RSS"
+        )?;
         writeln!(f, "{sep}")?;
 
         // compute all diagnoses up front (needed for both table and footnotes)
-        let diagnoses: Vec<Diagnosis> = self.stages.iter()
+        let diagnoses: Vec<Diagnosis> = self.stages.iter().map(|s| diagnose(s, n_cores)).collect();
-            .map(|s| diagnose(s, n_cores))
-            .collect();
 
         // per-stage rows
         for (s, d) in self.stages.iter().zip(diagnoses.iter()) {
-            writeln!(f, "{:<nw$}  {:>7}  {:>ew$}  {:>8}  {}",
+            writeln!(
+                f,
+                "{:<nw$}  {:>7}  {:>ew$}  {:>8}  {}",
                 s.label,
                 fmt_secs(s.wall_secs),
                 fmt_efficiency(s.parallelism(), n_cores),
@@ -508,11 +700,18 @@ impl fmt::Display for Reporter {
         let tw = self.stages.iter().map(|s| s.wall_secs).sum::<f64>();
         let tu = self.stages.iter().map(|s| s.user_secs).sum::<f64>();
         let ts = self.stages.iter().map(|s| s.sys_secs).sum::<f64>();
-        let trss = self.stages.iter().map(|s| s.max_rss_bytes).max().unwrap_or(0);
+        let trss = self
+            .stages
+            .iter()
+            .map(|s| s.max_rss_bytes)
+            .max()
+            .unwrap_or(0);
         let tpar = if tw > 1e-9 { (tu + ts) / tw } else { 0.0 };
 
         writeln!(f, "{sep}")?;
-        writeln!(f, "{:<nw$}  {:>7}  {:>ew$}  {:>8}",
+        writeln!(
+            f,
+            "{:<nw$}  {:>7}  {:>ew$}  {:>8}",
             "TOTAL",
             fmt_secs(tw),
             fmt_efficiency(tpar, n_cores),
@@ -520,7 +719,9 @@ impl fmt::Display for Reporter {
         )?;
 
         // bottleneck footnotes (only if at least one anomaly detected)
-        let bottlenecks: Vec<(&str, &str)> = self.stages.iter()
+        let bottlenecks: Vec<(&str, &str)> = self
+            .stages
+            .iter()
             .zip(diagnoses.iter())
             .filter_map(|(s, d)| d.detail.as_deref().map(|det| (s.label.as_str(), det)))
             .collect();