Extract the shared sampler/transform: 8 copies of the arithmetic is how the ChromBPNet CHIP bugs shipped

[lucapinello]

Why

All three ChromBPNet CHIP defects fixed on 2026-07-31 (#113, #120) were two copies of the same arithmetic disagreeing:

• exp vs expm1 on the count head (4 call sites, fixed independently);
• per-strand softmax vs one joint softmax over the flattened both-strand vector;
• a hardcoded (N,1) count-bias against a declared (None,2) input, which Keras silently broadcasts rather than rejecting — making an internal logsumexp return log(1)=0 instead of log(2) and shifting every predicted log-count down by a constant 0.5885.

None of these were caught by tests, because the oracle and the builder each had their own copy and the tests pinned each copy to itself.

The duplication, measured

concern	copies	shared?
ReservoirSampler	8 (one divergent: AlphaGenome hand-vectorises add_batch, capacity 20k vs 50k; one truncated)	no
one-hot encoding	6 in builders + 4 in the library, no two identical — (L,4) float32 vs (L,4) bool vs (4,L) vs (N,4,L)	no
get_sequence	8, with silently different N-fraction thresholds (0.5 vs 0.3)	no
TSS derivation	8, each reaching into the private AnnotationManager._get_genes_df while the public get_tss_positions sits unused	no
compute_effect	3 byte-identical + 1 hardcoded + 3 inlined	Cherimoya only
window scoring	3 identical get_window_slice + 2 score_window_sum	in words only
cCRE positions	an 11,500-position dict pasted 7×; sample_ccre_positions' own default (21,000) is dead code	partially

The precedent to generalise

chorus/oracles/cherimoya_source/scoring.py is imported by both the oracle and its builder, and says so deliberately — "so that class of drift [is] a type error rather than a silent numerical bias." Two patterns there are worth copying wholesale:

• tests/test_cherimoya.py:609 asserts the builder's source text contains the import, so the sharing cannot be quietly undone;
• the builder validates its fast GPU path against the shared reference on the first batch (assert_allclose(..., rtol=1e-4)), so sharing costs no throughput.

How to land it

Extract-then-migrate, so a regression blames exactly one oracle:

1. One PR adds the shared module and touches no builder.
2. Then one small PR per oracle, each proving byte-identical sample counts before/after.

The sampler must take the position set as an argument rather than hardcoding it — otherwise it blocks the reference-class work in #83 and the deferred activity-stratified design.

Two latent defects the extraction should absorb

• ChromBPNet silently halves its own effect CDF. The DHS-anchored SNP block is wrapped in except FileNotFoundError → logger.warning(...) (build_backgrounds_chrombpnet.py:450-451, again at :519). A build missing the vocabulary ships 9,609 effect samples instead of 18,672 and nothing fails. Cherimoya hard-fails in the same situation; that is the correct behaviour.
• Only EPInformer-seq validates the ref-allele substitution (if seq[offset] != ref_base: continue). The other seven substitute at a fixed INPUT_LENGTH // 2 - 1 and trust it. The arithmetic is correct today — but with 8 divergent copies of get_sequence, a windowing change would corrupt backgrounds silently rather than raise.

Also worth fixing while in here: _DHS_VOCAB_SHA256 (chorus/utils/annotations.py:731) is declared and never enforced — hashlib appears zero times in that file — while a comment at build_backgrounds_cherimoya.py:275-278 tells the reader the file "is checksummed". The cCRE Registry is fetched by bare urllib.request.urlretrieve with no verification, and the DHS vocabulary via hf_hub_download with no revision=, so it tracks a branch head.

Related: #83, #113, #120.

[lucapinello]

Sampling half is complete as of #162. The remaining scope is the transform half.

Done:

• ReservoirSampler, to_cdf_matrix, get_sequence, one-hot and the effect formulas live in chorus/analysis/background_sampling.py, with the four genuine behavioural divergences preserved as parameters rather than unified away (AlphaGenome capacity 20,000; LegNet's 0.3 N-threshold; log2fc/logfc/diff; EPInformer-seq's channels-first layout). Unifying any of those silently would move a shipped background, and whether LegNet's stricter threshold is intentional for a 200 bp window is a question for its owner.
• All eight builders now stage their samples (fix: reservoir sampling is all-or-nothing per position, so tracks share a variant set (#123) #150, fix: stage sampling in borzoi and alphagenome too, so the whole rebuild set is safe (#123) #151, Stage sampling in the last three builders, and drop the xfail that tracked them #162). The last five sites — chrombpnet 2, sei 2, cherimoya 1 — were behind a strict xfail; that marker is gone and the source-scanning guard passes on its own terms.
• add_batch was proved equivalent to the loop it replaces (test_add_batch_matches_where_a_builder_has_one exercises AlphaGenome's hand-vectorised version over a 400-value stream in 37-value chunks against a capacity of 40, so the replacement branch is actually hit). That settles the open question here: it is a safe optimisation, not a divergence.

Still open:

• Port the vectorised add_batch into the shared module and migrate the last builder to it. Kept out so far because the speed only matters for AlphaGenome's larger fan-out and a 3-line loop is easier to trust.
• compute_effect still has separate copies in alphagenome / borzoi / enformer.
• One-hot still has separate copies in sei / enformer / epinformerseq.

Deliberately staying per-builder, with reasons:

• get_sequence — ChromBPNet's takes a pysam handle where the shared helper takes pyfaidx. Unifying changes which positions are accepted as samples, not just how they are read.
• score_window_sum — ChromBPNet's 2*hw+1 spans 1001 bins against the shared 1000. Unifying shifts every ChromBPNet activity value.

One finding from #160 worth recording here, because it is this issue's thesis restated: build_config was being written by three producers in two array shapes (0-d from build_and_save, 1-element from Cherimoya's builder and from the stamp script). Every file on disk had the 1-element form, so a reader written against the shipped artefacts raised IndexError on anything build_and_save produced. Nothing compared them. Same class as the ChromBPNet CHIP bugs this issue was opened about.