Enum Ref 

pub enum Ref {
    Doi(Doi),
    Arxiv(ArxivId),
}

A reference to a paper, either by DOI or arXiv id.

See docs/SECURITY.md §1.1 for input-validation rules.

Variants

Doi(Doi)

A DOI (e.g., 10.1234/example).

Arxiv(ArxivId)

An arXiv id (e.g., 2401.12345).

Implementations

impl Ref

pub fn promote( &self, resolver_profile: &str, version: Option<&str>, ) -> CanonicalRef

Promote a Ref to a CanonicalRef under the given resolver profile and optional version (ADR-0021 §1).

resolver_profile MUST be the resolver key that produced (or is about to produce) the audit identity — e.g. "crossref" for Crossref metadata, "oa-publisher" for the publisher-side OA PDF leg, "arxiv" for arXiv. The string is byte-for-byte fed into the SHA-256 input.

version is the optional source-specific version token (arXiv "v2", Crossref snapshot date). None selects the empty-bytes branch of the digest algorithm.

impl Ref

pub fn parse(s: &str) -> Result<Self, RefParseError>

Parses a string into a Ref, auto-detecting DOI vs arXiv.

Detection rules:

1. If the input begins with the case-insensitive doi: scheme, the remainder is parsed as a DOI.
2. If the input begins with the arxiv: or arXiv: scheme, the remainder is parsed as an arXiv id.
3. Otherwise, if the input starts with 10. it is treated as a bare DOI; this matches the heuristic in docs/SAFEKEY.md §4 (Julia reference) and is stable because DOIs always begin 10..
4. Failing all of the above, parsing falls back to arXiv.

The returned Ref never carries the URI scheme — as_str() on the inner Doi / ArxivId is always the bare identifier.

Errors

Returns a RefParseError from the underlying Doi::parse or ArxivId::parse call. When the input has an explicit scheme (doi: / arxiv:), the matching parser is dispatched and its error surfaces directly. When the input is bare and ambiguous, the heuristic in rule 3/4 selects the parser; an unparsable bare input surfaces the arXiv parser’s error (a non-10. ref that also fails arXiv validation is never a valid DOI).

impl Ref

pub fn as_input_str(&self) -> &str

Returns the bare identifier string usable as a provenance ref field.

Equivalent to Doi::as_str / ArxivId::as_str dispatched on the variant — the URI scheme (doi: / arxiv:) is never present in the inner identifiers (it is stripped at parse time), so the result is always the bare DOI or arXiv id. Used by the CLI / MCP orchestrators to populate the ref column of provenance log rows (docs/PROVENANCE_LOG.md §3) without re-matching the variant.

pub fn safekey(&self) -> Safekey

Derives a deterministic, filesystem-safe key from this reference.

The algorithm is the NORMATIVE binding spec in docs/SAFEKEY.md §3. Both Rust and Julia implementations MUST produce bit-identical output for every entry in tests/fixtures/safekey/vectors.json.

Algorithm summary

1. Prefix with doi_ or arxiv_ (per variant).
2. Replace any character outside [A-Za-z0-9._-] with _.
3. Collapse consecutive _ runs to a single _.
4. Trim leading/trailing _.
5. If the result exceeds 192 bytes, take the first 192 bytes plus _ plus the first 8 hex chars of SHA-256(raw) (where raw is the step-1 output, before escaping).

The bound on as_str() after step 4 is pure ASCII (steps 1-3 produce only ASCII bytes), so the byte-slice in step 5 cannot split a multibyte char.

Trait Implementations

impl Clone for Ref

fn clone(&self) -> Ref

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ref

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Ref

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Hash for Ref

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Ref

fn eq(&self, other: &Ref) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Ref

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Ref

impl StructuralPartialEq for Ref