Key CRISPR guides on (anchor, protospacer) via disambiguate-on-collision

[Lioscro]

Problem

CrisprMapper identified each guide by its protospacer alone and fed the raw (un-deduplicated) protospacer column to seqhash::SeqHash::new, which rejects duplicate parents. On libraries where the same protospacer is deployed on both anchor scaffolds, the build aborts with:

parent at index 1 is duplicate of parent at index 0

This blocks cyto detect crispr, cyto map crispr, and the crispr workflow on such libraries (e.g. FLEXLIBPOOL009: 278 guides, 2 anchors, 6 protospacers shared across the two anchors).

Fix

Key guide identity on the (anchor, protospacer) pair via disambiguate-on-collision:

• Dedup protospacers before hashing — SeqHash never sees a duplicate parent, so the crash is structurally impossible.
• Unique protospacer → ignore the anchor (the overwhelming common case) — behavior byte-identical to today.
• Shared protospacer → the matched anchor selects the guide; a matched anchor carrying none of that protospacer's guides is unmapped (None).
• feature_idx is now the 0-based TSV row index (contiguous 0..N, aligned in order with names / record_stream() / metadata/features.tsv).
• Two rows identical in both anchor and protospacer are a load-time error naming both guides (replaces the opaque seqhash message).
• statistics() reports the true guide count; an info! line logs when protospacers are shared.

Change is confined to crates/cyto-map/src/mapper/crispr.rs (plus two test fixtures and a CLAUDE.md doc update). The downstream pipeline (processor.rs → cyto-ibu-count → workflow) is feature-index-agnostic and unchanged.

Scope: previous behavior explicitly retained (decision deferred)

This change is deliberately minimal. The previous mapping behavior is explicitly retained: a protospacer is matched regardless of anchor for every guide whose protospacer is unique (the common case). The anchor is consulted only to break ties among the rare protospacers shared across anchors — the minimum needed to fix the build crash without changing mapping outcomes for any library that builds today.

This PR does not make the anchor a mandatory part of guide identity (i.e. strict (anchor, protospacer) pairing enforced on every read). That is a broader decision — it would change mapping rates for all libraries — and is deferred until we decide whether the anchor should also be considered as part of guide identity generally.

Testing

• cargo test -p cyto-map: 77/77 (7 new unit tests covering collision resolution with exact per-anchor row index, unique-protospacer backward-compat, wrong-anchor→None, dup-pair error, statistics/row-count, exact=true build, real-library guard). clippy clean (no new warnings), fmt clean.
• Mutation check: neutering the disambiguation branch fails exactly the two collision tests and passes when restored.
• Regression proof (real data): the exact bug-report cyto detect crispr on FLEXLIBPOOL009 now exits 0, emits geometry [barcode][umi:12] | [:2][probe][anchor][protospacer], and logs 6 protospacer(s) shared across anchors; disambiguating by anchor — no duplicate error.
• FLEXLIBPOOL009 features.tsv = 278 rows, all 12 shared-protospacer guides present as distinct rows.
• Zero regression: standard-library data/libraries/crispr_guides.tsv features.tsv is byte-identical between main and this branch (6066 rows, matching md5).

Note

cargo test --workspace may show a cyto-download::run_uses_server flake (localhost HTTP port contention); it passes in isolation and that crate is untouched by this PR.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the CRISPR mapper to support disambiguating guides when a protospacer is shared across multiple anchors. It introduces a new proto_guides mapping, rejects duplicate anchor-protospacer pairs at load time, and updates the query logic to resolve collisions based on the matched anchor. The review feedback suggests destructuring the CrisprRecord during deserialization to avoid unnecessary string clones, which is a valuable performance improvement.