docs: tutorial notebook `02_score_brca2_saturation.ipynb`

[AbdelStark]

Context

Headline visual demo: BRCA2 saturation mutagenesis heatmap.

Scope

• Score every possible SNV across a BRCA2 exon.
• Heatmap of calibrated surprise.
• Compare to Findlay et al. functional scores.

Out of Scope

Design Reference

• examples/README.md

Acceptance Criteria

• Notebook reproduces published BRCA2 baseline within ±0.05 Spearman

Parent tracking issue: #20

[AbdelStark]

Blocked (session-scoped): tutorial depends on APIs that have not yet shipped.

Tutorial notebooks demonstrate the end-to-end user journey through geno_lewm.{encoder,score_variant,plan,read_receipt,...}. Those APIs themselves depend on the ML stack that this session could not bring up (see comments on the encoder / predictor / training / surprise / planning issues). Writing a tutorial against missing APIs would either:

• Hard-code expected outputs against code that does not exist (false demo), or
• Ship a notebook that does not execute (broken docs).

Notebook(s) that ARE buildable today (might be picked up in a follow-up):

• 07_verify_receipt.ipynb (docs: tutorial notebook 07_verify_receipt.ipynb #99) is the closest to feasibility because geno-lewm-verify and geno_lewm.provenance already ship (provenance: implement content-addressed model IDs + manifest schema #74, provenance: implement input commitment #75, provenance: implement checksum receipt writer/reader #76, provenance: implement geno-lewm-verify CLI (checksum mode) #77 merged this session). A tutorial showing manifest/receipt round-trip is constructible against the current package; what's missing is a real (non-mock) receipt produced by an actual scoring call, which still depends on the ML stack.

To pick up: wait for the relevant upstream issue (#62 / #65 / #59 / #66 / etc.) to land, then implement.

[AbdelStark]

Blocked on the scoring runtime, calibration path, and BRCA2 comparison artifacts.

Evidence:

• This notebook requires scoring every possible SNV across a BRCA2 exon and reproducing a published BRCA2 baseline within +/-0.05 Spearman.
• The current scoring CLI is still a stub (geno_lewm/cli/score.py -> surprise: publish clean-machine geno-lewm-score transcript #65), and GenoLeWMRuntime.score_variant() fails fast because no scorer backend/checkpoint exists.
• Upstream scorer issues surprise: validate scoring APIs against released artifacts #62/surprise: publish clean-machine geno-lewm-score transcript #65 are marked status:blocked.
• The benchmark also needs a committed or fetchable Findlay et al. comparison fixture plus calibrated surprise outputs, which do not exist in the current repo state.

Why not write the notebook now:

• Synthetic or hard-coded heatmaps would not satisfy the Spearman acceptance criterion.
• An unexecuted notebook would fail the examples convention and docs acceptance.

To unblock:

• Land the scorer/calibration stack and provide the BRCA2 comparison fixture plus expected baseline target.