feat: implement exact seeded base-pair probabilities (#257)

[Alexander-Mitrofanov]

Exact seeded --model=P --mode=M prediction now counts each complete interaction once, even when it contains several overlapping or disjoint seeds. --out=bpProb:FILE reports actual interior-pair probabilities over the union of searched disjoint regions, using the same raw partition denominator as prediction without pair output.

The implementation follows the reviewed plan on this existing branch in seven separate commits, one per step:

1. 88f4369: Establish an independent exhaustive weighted-chain oracle and all ten unrounded theory fixtures.
2. 62afc24: Compile geometric stack-seed capability, active occurrences, and eligible domains.
3. 5c8907c: Validate and compare both kernel candidates and select the suffix kernel.
4. 8bd8534: Integrate unique partition accounting, shared boundary coefficients, extension hooks, and exact-zero handling.
5. 99919de: Accumulate raw pair masses in original coordinates across successful disjoint regions.
6. 3f6d3d1: Expose the matrix writer and CLI output, including multiFASTA, gzip, and shared streams.
7. 48efc54: Complete validation, documentation, performance measurements, installed consumer checks, and packaging.

Stack-seed admission is preserved, including accepted mixed-length and singleton explicit seeds. Existing bulged and heuristic prediction paths remain available; unsupported combinations with bpProb fail explicitly. The new matrix contains actual pairs; existing spot output retains its coverage interpretation. Successful empty searches produce NA entries. Numerical range errors fail explicitly without a scaling fallback, and failed calculations do not publish a partial probability matrix. Corrected partition accounting can change ensemble results; no golden output was regenerated to conceal differences.

Validation:

• GCC 14.4 release and debug builds each pass all seven test suites, including 91,361 API assertions in 85 cases.
• Both kernels agree with independent enumeration across ten theory fixtures and 100 randomized heterogeneous cases, plus native energy and accessibility checks.
• CLI checks cover reporting invariance, disjoint regions, signed coordinates, GU admission, tiny partitions, singleton and mixed seeds, empty searches, unsupported modes, I/O failures, scientific notation, gzip, and serial/parallel multiFASTA output.
• All 74 installed public headers compile independently. The installed predictor example links through pkg-config; the missing -leasylogging dependency is fixed and CI now runs this consumer.
• make dist succeeds and includes all 23 new distributable files. Encoding and git diff --check pass.
• The native OxyS–fhlA measurement takes a median 0.09 s without the matrix and 0.16 s with it over three runs, with identical raw partition totals. These figures compare output modes, not legacy performance.

See kernel comparison and validation report for reproducible commands and limitations. Apple Clang validation is left to the existing macOS CI because that toolchain is unavailable locally.

Addresses #257.

[martin-raden]

@Alexander-Mitrofanov

thanks, implement the plan in multiple commits (at least one per step) to this branch

[martin-raden]

@Alexander-Mitrofanov

thanks, please add the following steps:

(step 8) SVG dot plot output

• investigate the preliminary implementation of an RRI dotplot SVG output in
  • https://github.com/BackofenLab/IntaRNA/blob/dev-frank/src/IntaRNA/PredictionTrackerProfileSpotProb.h
  • https://github.com/BackofenLab/IntaRNA/blob/dev-frank/src/IntaRNA/PredictionTrackerProfileSpotProb.cpp
• implement a similar SVG output format with the current base pair proability architecture enabled with the commandline output file argument "bpsvg=fileOrStreamName"

general SVG requirements:

• sequence names are x/y "axis" labels
• sequence nts are provided as surrounding frame
• 1-nt unpaired probabilities are provided as surrounding frame of filled rectangles to highlight local accessibility of sequences. the filling gradient encodes the unpaired probability
• probability gradients are to be implemted as segmented gradient, e.g.

linear-gradient(90deg, 
  #FFFFFF 0%, #FFFFFF 25%, 
  #AEC6CF 25%, #AEC6CF 50%, 
  #4682B4 50%, #4682B4 75%, 
  #002060 75%, #002060 100%
);

• for the gradient, use at least 6 color steps following the suggestion from above to enable a visual distinction of probability value (classes)

• below the plot, add a color gradient legend for the respective probability value ranges

• ensure the color gradient is css based and defined in a way that it can be easily adapted later

• use the same color gradient for the base pair probability rectangles in the central matrix

• add gray colored guiding lines

  • every 10th, 50th nt using the final sequence index, i.e. if a sequence starts at -15 put the first guide line between -10 and -11
  • since the index 0 is missing, add a guide line between +1 and -1 if both are present in the sequence

• add sequence indices at the guiding lines

  • add the index beside "+1" or every 10th nucleotide wrt its final index

• add hover information to each probability rectangle showing the respective index (combination), probability type and value

• if the base pair probabilities are seed-restricted predictions, add dark orange rectangle boundaries to all probability cells that are part of a seed.

  • add a respective information to the legend if this annotation is added

(step 9) recursion depiction

• add recursion depictions for ensemble based predictors and base pair probability computation in doc/recursions
• no linking needed, the SVGs are for internal documentation only

[martin-raden]

@Alexander-Mitrofanov

thanks, please revise:

• do a "git update" to get the recent changes to this branch
• implement the following issues

[martin-raden]

• when encoding base pair information, use IntaRNA::Interaction::BasePair instead of "std::pair" or "std::array"
  • provides already a hash function
• for sparse data storage (typical for seed starts) use a hash(map) rather than a std::map.
  • replace this using "std::unordered_map<BasePair, size_t, BasePair::Hash>"

[martin-raden]

• update AGENTS.md with respective guidelines for similar upcoming changes

[martin-raden]

• generally: extend documentation level of function implementations with inline comments summarizing subsequent steps similar to remaining code, to simplify human code and sanity checks

[martin-raden]

• check internal invariants like this with assert or NDEBUG precompiler checks that are not checked in release code
• only to release-code checks for input validation and checks that might fail during normal execution
• extend the AGENTS.md with respective guidelines