Module reference 

A citable external work — the record a reference list is rendered from (issue #801, phase 3).

This module holds the data and nothing else. It knows what we have been told about a work; it has no opinion about how a reference is spelled, which fields a citation style insists on, or whether the result is fit to publish. Those are a renderer’s judgements and live with the renderer — rto_render’s apa module. That is deliberately not a link: this crate does not depend on rto-render, and a link that resolved would mean the dependency ran the wrong way.

The three states, and why two of them look alike

The defect this module exists to prevent is a plausible citation. A reference with a guessed year is worse than no reference at all, because it survives review: it looks like the others.

Almost every field of a real bibliographic record is in one of three states, and the middle one is the trap:

state	meaning	citable?
Attested::Known	we hold the value	yes
Attested::AbsentFromWork	somebody looked, and the work has none	yes — APA writes n.d. for a dateless work, and that is an honest thing to write
Attested::Unknown	nobody has looked it up	no

AbsentFromWork and Unknown are both “there is no value here”, which is exactly why they must not share a spelling. n.d. is a claim about the work — it asserts that the work carries no date. Rendering an unresearched field as n.d. publishes that claim on no evidence, and it is indistinguishable in the output from the honest case. So the two are separate variants, the Default is Attested::Unknown, and a record built field by field refuses until somebody has been through it.

There is no Option on any field a renderer consults, for the same reason: None would collapse the two states back together.

What is unrepresentable rather than refused

Two conditions are modelled so that the bad state cannot be written down at all, which is stronger than catching it later:

• A retrieval date belongs to the condition that requires it. APA asks for one only where a work is designed to change and is not archived, so the date lives inside that variant of Stability. “Changeable, with no retrieval date” and “stable, but here is a retrieval date I will quietly emit” are both unspellable.
• A publication date is a year, or a year and a month, or a full date. PublicationDate is an enum rather than a struct of Options, so a day without a month cannot be recorded.

No clock, and no network

Nothing here reads the time. A retrieval date is data on the record, written down by whoever did the retrieving; SystemTime::now() would make a rendered bundle differ on every build, and ADR-0013 is explicit that no wall-clock value may reach a query. The module is a plain data definition: no I/O, no clock, no graph access.

It lives in this crate — not in the renderer — for two reasons. The extraction layer that will eventually populate these records is here, and a type cannot be shared upwards: rto-render depends on rto-graph, so the record must sit in the lower crate for both to name it. And this is the crate that structurally cannot reach the network — gix is pinned default-features = false to exclude transports (ADR-0019 §2) — which is the guarantee worth having over a type whose every field invites a lookup.

Structs

AccessDate

The date on which somebody retrieved a work, written down by whoever did it.

Day

A day of the month, 1 through 31.

Doi

A Digital Object Identifier, held bare (10.3886/ICPSR36966.v1).

GivenName

One given name, as the work spells it: Mary, or M. where that is all anybody recorded.

NotADay

A day outside 1..=31.

NotADoi

A string that is not a DOI.

NotAGivenName

A string that is not a usable given name.

NotAYear

A year of zero or less.

Reference

A citable external work.

Year

A year a work was published or was retrieved in, 1 or later.

Enums

Attested

What is known about one field of a Reference.

Author

Who produced a work.

Locator

Where a work can be found online.

Month

A calendar month, named rather than numbered so that an impossible month cannot be recorded.

PublicationDate

When a work was published.

Stability

Whether a work holds still.

WorkKind

What kind of thing a work is.

Functions

is_printable_identifier

Whether every character of text is one a reader can see and a URL can carry: an ASCII graphic character, ! through ~.