Enum Provenance 

pub enum Provenance {
    Derived,
    Authored,
    Inferred,
    ExternalDerived,
    ExternalAuthored,
    ExternalInferred,
}

How an edge or node in the graph was produced.

Six tokens, because “external” is a modifier and not a class

Three of these describe work this graph did: deterministic extraction, human authorship, heuristic inference. The other three describe the same three claims made by someone else, imported from a peer repository’s Open Knowledge Format bundle ([[docs/adr/0021-open-knowledge-format-bundle.md]]).

The peer’s tier is carried rather than collapsed, and that is the whole point of the shape. crate::Provenance is matched exhaustively by rto_render::okf::origin_for to produce OKF trust tiers, so a single flat External would force one arm — and therefore one answer for everything imported. Either it maps to unverified, which downgrades a peer’s human-reviewed concept, or it maps to machine-confirmed, which upgrades their similarity guess. render okf then re-emits that flattened tier outward to the next consumer: laundering by round-trip, in a format adopted specifically because it can express the distinction.

Externality does not nest

A fact we imported from B, which B had imported from C, is external-* — not doubly external. Provenance::externalise is idempotent for exactly that reason. Which repository the fact came from is not a property of the fact: it is the import layer’s src_ref, which names B.

What “external” does not modify

An external-inferred edge carries no confidence, where a local Provenance::Inferred one must (see crate::Edge::is_valid). A confidence is a number we computed; OKF carries none for a relationship, so adopting one would mean inventing it. That asymmetry is deliberate and is enforced by the store’s own CHECK as well as by Rust.

Compatibility

This enum had three variants up to and including 5.0.0; the three External* variants arrived in 5.1.0. It is pub, re-exported from the crate root, and deliberately not #[non_exhaustive] ([[docs/adr/0001-build-roteiro-unified-codebase-knowledge-graph.md]] v1.3 argues why that is the right shape), so the addition is technically breaking for anyone who matches it exhaustively.

It shipped as a minor, deliberately and per policy: AGENTS.md treats the rto-* crates’ public surface as internal, since they publish only so that cargo install roteiro resolves and roteiro is their sole reverse dependency. This note is the record that posture asks for, not a dissent from it.

If you do depend on this crate directly, two concrete consequences:

• An exhaustive match over the old three variants stops compiling. Add the three arms, or match with a wildcard if you only care about the local classes. A match that already had one is unaffected.
• The serialized tokens are additive, so a 5.0.0 consumer reading a document written by 5.1.0 or later rejects external-derived, external-authored and external-inferred as unknown variants. Provenance rides every edge of every roteiro.query/v1 document. On disk the guard for this is migration 14, which makes an older build report such a store as written by a newer Roteiro rather than as corrupt ([[docs/adr/0021-open-knowledge-format-bundle.md]]).

Variants

Derived

Deterministically extracted from source ASTs (tree-sitter). The default: the overwhelmingly common node/edge, and the correct value when a legacy cached fact set (serialized before nodes carried provenance) omits it.

Authored

Authored by a human or agent in an ADR, blueprint, or annotation.

Inferred

Heuristically inferred (docs, embeddings); carries a confidence score.

ExternalDerived

A peer’s Provenance::Derived fact, imported from their bundle.

They could re-derive it from their AST; we cannot, because we do not have their tree. So this asserts they say it is deterministic, and nothing about our ability to check.

ExternalAuthored

A peer’s Provenance::Authored fact, imported from their bundle.

Someone confirmed it in their repository. Importing it as Provenance::Authored would assert that this graph human-authored it, which is the laundering the whole variant exists to refuse.

ExternalInferred

A peer’s Provenance::Inferred fact, imported from their bundle — or any imported fact taken at acknowledge rather than trust: their information without their confirmation.

Implementations

impl Provenance

pub fn from_token(s: &str) -> Option<Self>

Parse a provenance from its stable string token, returning None for an unrecognised value.

Two things produce one: a corrupt database row, and a store written by a newer Roteiro that knows a token this build does not. The second is not hypothetical — this build added three — and it is diagnosed before a row is decoded, by crate::Store::schema_ahead: every widening of this set ships with a migration, so a store carrying an unknown token necessarily records a migration this build has never heard of.

Deliberately not tolerant of an unknown token. A fallback value would have to be one of the six, and every choice is a claim: assuming derived upgrades an unknown to machine-confirmed, assuming inferred downgrades a confirmed fact. That is the same laundering the external variants exist to prevent, arriving through the error path instead.

pub fn as_str(self) -> &'static str

Stable string form used in the SQLite store.

pub fn tokens() -> &'static [&'static str]

Every token, in the order the enum declares them — the exact set Provenance::from_token accepts and the store’s CHECK permits.

Exists so an error message, a schema and a test can each name the vocabulary without writing a fourth copy of it down.

pub fn is_external(self) -> bool

Whether this fact came from another repository’s bundle rather than from this graph’s own work.

pub fn tier(self) -> Self

The tier this provenance claims, with externality stripped: what kind of claim it is, ignoring whose claim it is.

Use it where the question is genuinely about the tier — rendering a trust level, ranking a fact’s strength. Do not use it to decide whether a fact may be rewritten, re-derived or asserted as this graph’s own: those questions are about ownership, and Provenance::is_external answers them.

pub fn externalise(self) -> Self

This provenance as a peer’s claim: the external variant carrying the same tier.

Idempotent, and that is the decision rather than a convenience. Externality flattens to one level: a fact imported from B that B imported from C is external-*, not doubly external, because the fact is external exactly once and which repository it arrived from is the import layer’s src_ref, not the fact’s class.

Trait Implementations

impl Clone for Provenance

fn clone(&self) -> Provenance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Provenance

impl Debug for Provenance

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

Formats the value using the given formatter.

impl Default for Provenance

fn default() -> Provenance

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Provenance

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Provenance

impl PartialEq for Provenance

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for Provenance

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Provenance