Persistent, provenance-carrying identifiers for MaveDB functional evidence

[bencap]

Summary

Manuscript review raised a double-counting risk: if a lab has already used a MAVE as functional evidence in a ClinVar submission, a MaveMD user may unknowingly apply the same evidence a second time. The suggestion was a stable, DOI-style identifier per piece of evidence, carrying provenance and metadata, so ClinGen panels and labs can cite exactly what they used. The reviewer only asks for discussion-section commentary, so this is not blocking. But it is a real design question and worth settling a position and direction on.

What already exists

More of this is in place than the framing suggests. Our annotation document layer already mints identified, resolvable references:

• Experiments, score sets, and score calibrations each become a document whose id is the entity's URN.
• Each carries a resolvable frontend URL; the calibration URL is a deep link that selects the specific calibration.

So a citable coordinate substantially exists today: score set URN plus calibration URN, both resolvable. The open question is narrower than "invent an identifier". It is whether that coordinate is sufficient, whether the citation is also applicable to variant level pages, and what guarantees it needs to become citable in earnest.

Questions to resolve

1. What is the citable unit? The measurement (variant x score set), the interpretation (variant x score set x calibration), or the full annotation chain (variant x score set x calibration x annotation)?
2. External registration or internal identifier? Do ClinGen panels need a registered DOI (e.g. DataCite) to cite this in their workflows, or is a stable resolvable URL under our own namespace sufficient? Registration carries an ongoing obligation.
3. Provenance payload. What must travel with the identifier to make a citation self-describing: score, calibrated evidence strength and direction, assay method, publication, retrieval date, calibration version?
4. Whose job is detection? Is surfacing "this evidence already appears in ClinVar submission SCV…" a MaveDB responsibility, or do we only provide the citation hygiene that makes double-counting visible to a human reviewer?
5. Temporal reproducibility. A citation is only reproducible if we can serve the evidence as it stood on the citation date. Optimize Variant Classification Functions to Avoid ORM Relationship Loading #657 tracks as_of historical variant views. That capability and this one are coupled and should be reasoned about together.

Definition of done

• A recorded design position sufficient to write the manuscript discussion paragraph.
• Follow-up implementation issues for whatever part of it we intend to build.

Notes

• Related: Optimize Variant Classification Functions to Avoid ORM Relationship Loading #657 (as_of temporal views).