Struct Provenance 

pub struct Provenance {
    pub source: Source,
    pub observed_at_ns: i64,
    pub status: Status,
}

Everything a consumer needs to decide how far to trust one value.

A view type, built on demand rather than stored: the index keeps one Source byte per entry and its observation timestamps once, because on a tree of millions of entries the timestamps are shared by nearly all of them and a per-entry struct would cost more memory than the information is worth.

The three facts are independent on purpose, because they answer different questions. Status asks how much of the subtree the number covers; Source asks how far to trust what it covers; observed_at_ns asks when. A Status::Complete but Source::Cached value is a point estimate that may move either way and reads as “about 3.2 GB, as of two minutes ago”, while a Status::Partial value is missing part of its subtree and reads as “3.2 GB so far”. Collapsing them would make a shrinking number look like a defect.

Note that “3.2 GB so far” is only a lower bound that grows while an additive walk is running. See Status::Partial: the status records coverage, not direction.

Fields

source: Source

Where the value came from.

observed_at_ns: i64

When the underlying filesystem observation was made, in nanoseconds since the Unix epoch. For Source::Cached this is when the snapshot captured it — the “as of” a consumer displays. Zero when unknown.

status: Status

How settled the value is.

Implementations

impl Provenance

pub const fn scanned(observed_at_ns: i64) -> Self

Freshly observed by this process, complete.

pub fn combine(self, other: Self) -> Self

Combine with another value’s provenance, taking the less trustworthy of each fact.

This is what makes a directory only as trustworthy as its least trustworthy descendant: the weakest source, the oldest observation, and the worst status.

Every fact fails closed, including time: an unknown observed_at_ns is absorbing rather than skipped, so a subtree with one contributor of unknown age reports an unknown age instead of a precise time it cannot prove.

There is deliberately no identity element. Because unknown is absorbing, it cannot double as the seed of a fold, and a caller aggregating a possibly-empty set must represent emptiness separately (Option<Provenance>) rather than seeding with a zero timestamp — otherwise every roll-up would come out unknown.

pub const fn is_verified(self) -> bool

Whether this value was checked against the filesystem during this session.

Trait Implementations

impl Clone for Provenance

fn clone(&self) -> Self

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 Eq for Provenance

impl PartialEq for Provenance

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Provenance