Struct ItemRef 

pub struct ItemRef {
    pub logical_path: String,
    pub is_dir: bool,
    pub content_hash: Option<String>,
    pub size: Option<u64>,
    pub media_type: Option<String>,
    pub projection_hint: ProjectionHint,
    pub tabular_parse: Option<TabularParseConfig>,
    pub handle: String,
}

Metadata-only view of one side of a comparison. Carries logical identity and content metadata but NOT a filesystem path — data access goes through DataAccess.

Metadata invariants

content_hash, size, and media_type are opportunistic hints. Producers (expand rules like directory/zip, or data backends) populate them when doing so is cheap — typically as a byproduct of work they were already performing. Consumers must not assume presence, but may trust presence: when a field is set, the value accurately reflects the current bytes. Use ItemRef::resolve_hash / ItemRef::resolve_size to obtain a value with a transparent fall-back read.

This keeps fast paths (directory-only listings, short-circuit identical detection) cheap while letting consumers that need a value — most notably the move detector, which correlates leaves across container boundaries — hydrate on demand.

Fields

logical_path: String

User-meaningful location within a snapshot. /> marks a decompose boundary; a literal segment beginning with > is escaped as \>.

is_dir: bool

content_hash: Option<String>

size: Option<u64>

media_type: Option<String>

projection_hint: ProjectionHint

Optional projection metadata supplied by rule packs while they still know the vocabulary. Core carries this through but does not interpret file names, media types, or plugin-specific tags.

tabular_parse: Option<TabularParseConfig>

Optional stdlib-resolved tabular parse hints carried from dataset config to whichever tabular parser eventually claims this item.

handle: String

Opaque identifier used by DataAccess implementations to locate data. Plugin authors should not create or interpret this value directly.

Implementations

impl ItemRef

pub fn extension(&self) -> Option<String>

pub fn resolve_hash(&self, data: &dyn DataAccess) -> BinocResult<String>

Return the item’s BLAKE3 content hash, computing it from bytes if not already cached on this ItemRef. Never valid for directories.

pub fn resolve_size(&self, data: &dyn DataAccess) -> BinocResult<u64>

Return the item’s byte length, reading from the backend if not already cached on this ItemRef. Never valid for directories.

Trait Implementations

impl Clone for ItemRef

fn clone(&self) -> ItemRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ItemRef

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ItemRef

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for ItemRef

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

where __S: Serializer,

Serialize this value into the given Serde serializer.