# Exploit: Variant to protein-structure annotation

## Winning Approach

The winning explore approach is the thin direct-source join: resolve the exact gene+protein variant with MyVariant.info, resolve the protein/structures through UniProt, parse InterPro residue ranges for domain overlap, and attach the existing BioMCP Cancerhotspots recurrence signal. AlphaFold and PDB links can be generated from UniProt cross-references. RCSB probing is not needed for the first contract.

The ticket is an investigation-only spike, not a production build ticket. Full scale for this exploit therefore means the full ticket-scale benchmark and deliverable: all three named variants, all required source families, source-labelled degradation behavior, and a durable recommendation artifact. No production feature code was added.

## Full-Scale Results

Target scale: BRAF V600E, TP53 R175H, and ROS1 G2032R across MyVariant.info, UniProt, InterPro, and Cancerhotspots.

Measured with `architecture/experiments/variant-structure-annotation/scripts/run_experiments.py --approach all` plus one direct rerun to check live-source latency noise.

| Variant | Residue | MyVariant | UniProt | PDB count | AlphaFold | InterPro overlaps | Cancerhotspots | Direct total latency |
|---|---:|---|---|---:|---|---:|---|---:|
| BRAF V600E | 600 | ok | ok | 131 | P15056 | 4 | present | 32003 ms |
| TP53 R175H | 175 | ok | ok | 295 | P04637 | 4 | present | 7022 ms |
| ROS1 G2032R | 2032 | ok | ok | 5 | P08922 | 5 | present | 27006 ms |

The full-scale run reproduced the core result: all three variants can be tied to a requested amino-acid residue, overlapping InterPro domains, PDB IDs, AlphaFold IDs/links, and a source-labelled Cancerhotspots response.

## Regression Control

Regression control used the same three variants and the same direct-source methodology from explore. Correctness matched explore exactly for the contract fields.

| Variant | Explore residue / PDB / overlaps / latency | Exploit residue / PDB / overlaps / latency | Result |
|---|---|---|---|
| BRAF V600E | 600 / 131 / 4 / 15568 ms | 600 / 131 / 4 / 32003 ms | Correctness pass. Latency literal fail; waived as live-source measurement noise. |
| TP53 R175H | 175 / 295 / 4 / 17513 ms | 175 / 295 / 4 / 7022 ms | Correctness pass. Latency pass. |
| ROS1 G2032R | 2032 / 5 / 5 / 19955 ms | 2032 / 5 / 5 / 27006 ms | Correctness pass. Latency literal fail; waived as live-source measurement noise. |

Latency carveout applied to BRAF and ROS1. The rule waived is the 3% latency rule. The source outputs and correctness counts were unchanged, while repeated live runs showed large endpoint jitter without code changes. In the first full run, BRAF direct latency was 30235 ms with InterPro taking 26762 ms; the immediate direct rerun was 32003 ms. ROS1 moved from 19929 ms in the first full run to 27006 ms in the direct rerun. The optional structure-link run showed the same correctness with different live latencies again (BRAF 16364 ms, TP53 25258 ms, ROS1 15671 ms). This pattern supports live-source noise, not a real implementation regression.

No projection/output checksum rule applies here because the spike produces source-observation JSON, not a deterministic projection artifact.

## Validation

Validated:
- The direct-source join still resolves the requested protein positions for all three variants.
- MyVariant transcript/isoform ambiguity is visible instead of hidden: all three variants had `position_consistent: false`, so a production contract must preserve requested HGVSp matches and other source positions.
- InterPro location ranges are present and support residue-overlap checks.
- UniProt provides enough PDB and AlphaFold cross-reference data for the first BioMCP contract.
- Cancerhotspots returns source-labelled output for all three test variants.
- Existing CLI composition still reaches variant, protein structures, and protein domains, but it still does not expose domain ranges, so it cannot safely answer residue-overlaps-domain by itself.
- ΔΔG/stability-effect computation remains out of scope because it would cross BioMCP's read-only annotation boundary and require heavyweight modelling dependencies.

Validation commands run:
- `architecture/experiments/variant-structure-annotation/scripts/run_experiments.py --approach all`
- `architecture/experiments/variant-structure-annotation/scripts/run_experiments.py --approach direct`
- `git status --short`
- `git ls-files .march .claude architecture/experiments/variant-structure-annotation/results`
- `find architecture/experiments/variant-structure-annotation -maxdepth 3 -type f -size +5M -print`

No source/spec code changed, so `make lint`, `make test`, and `make spec` were not re-run for this investigation-only artifact update.

## Produced Artifacts

Persistent locations:
- `architecture/experiments/variant-structure-annotation/exploit.md` — copied report for downstream readers.
- `architecture/experiments/variant-structure-annotation/results/direct_source_join.json`
- `architecture/experiments/variant-structure-annotation/results/direct_source_join_summary.json`
- `architecture/experiments/variant-structure-annotation/results/direct_source_join_with_structure_links.json`
- `architecture/experiments/variant-structure-annotation/results/direct_source_join_with_structure_links_summary.json`
- `architecture/experiments/variant-structure-annotation/results/existing_cli_composition.json`
- `architecture/experiments/variant-structure-annotation/results/existing_cli_composition_summary.json`
- `architecture/experiments/variant-structure-annotation/results/exploit_regression_control.json`

`.march/exploit.md` is the March runtime copy and must not be committed.

## Contract Numbers

Downstream spikes can depend on these exploit-measured values for the first BioMCP `variant structure` build contract:

| Variant | Requested residue | PDB count | AlphaFold ID | Overlapping InterPro domains | Direct observed latency |
|---|---:|---:|---|---:|---:|
| BRAF V600E | 600 | 131 | P15056 | 4 | 32003 ms |
| TP53 R175H | 175 | 295 | P04637 | 4 | 7022 ms |
| ROS1 G2032R | 2032 | 5 | P08922 | 5 | 27006 ms |

Contract shape recommendation:
- Public surface: `biomcp variant structure "BRAF V600E"` and `biomcp --json variant structure "BRAF V600E"`.
- Default `get variant` remains unchanged; structure is opt-in only.
- Output must include source labels for variant/residue, protein, domains, structures, AlphaFold, and Cancerhotspots.
- Output must expose requested HGVSp matches, other source protein positions, and a position-confidence field.
- Output must include `_meta.next_commands` for protein structures/domains and variant articles.
- Graceful degradation must return partial source-labelled output and warnings, not fabricated zeros.

Follow-on build files/spec layers named by the spike:
- `src/entities/variant*` for the structure helper model/orchestration.
- `src/sources/interpro.rs` for location/range parsing.
- `src/sources/uniprot.rs` for typed PDB/AlphaFold rows and chain coverage strings.
- `src/render/markdown/variant*` and JSON helper/rendering for output and `_meta.next_commands`.
- CLI wiring under `src/cli/*`.
- Docs: `docs/user-guide/cli-reference.md`, `architecture/ux/cli-reference.md`, and variant user docs.
- Specs: `spec/entity/variant.md` or `spec/entity/variant-hotspots.md`.
- Tests: request-contract test, renderer unit test, and a real behavioral check on the operator/real-local lane with live sources.

## Conclusions

Go. BioMCP can answer variant-to-structure annotation using existing read-only federated sources, with a modest production feature rather than a new structural modelling pipeline.

What this enables:
- A safe opt-in helper that connects exact variants to residue, domain, PDB, AlphaFold, and Cancerhotspots context.
- Honest transcript/isoform reporting instead of silently treating the first MyVariant position as canonical.
- A follow-on build ticket with clear files, output fields, and test layers.

Remaining risks:
- Live endpoint latency is noisy; the command must stay opt-in and should use BioMCP's existing cache/status conventions where possible.
- InterPro range parsing needs fixture tests because the data is present in live responses but absent from current BioMCP domain models.
- UniProt chain coverage strings are useful but compact; production parsing should keep raw strings and only mark residue coverage when the range parse is clear.
- RCSB residue-level coordinate mapping remains a later enhancement, not a dependency for the first contract.
