uor-foundation 0.4.5

// @generated by uor-crate from uor-ontology — do not edit manually

//! `u/` namespace — Content-addressable identifiers for ring elements. Each element carries a unique content-derived identifier..
//!
//! Space: Kernel

use crate::HostTypes;

/// A content-addressable ring element. Each Element uniquely identifies a piece of content via its hash-derived identifier.
pub trait Element<H: HostTypes> {
    /// The number of Braille glyphs in an address string.
    fn length(&self) -> u64;
    /// The datum that this address references. Inverse of schema:glyph.
    fn addresses(&self) -> &H::HostString;
    /// The content hash of this address. Format: (blake3|sha256) colon followed by 64 lowercase hex characters. The algorithm prefix must match u:digestAlgorithm.
    fn digest(&self) -> &H::HostString;
    /// The hash algorithm used to produce u:digest. Allowed values: 'blake3' (primary), 'sha256' (secondary).
    fn digest_algorithm(&self) -> &H::HostString;
    /// The canonical byte serialisation of the addressed datum, per Amendment 43 section 2: header(k) || le_bytes(x, k+1). This is the exact byte string hashed to produce u:digest.
    fn canonical_bytes(&self) -> &H::WitnessBytes;
    /// The Witt level n of this element. The element encodes a datum in R_n = Z/(2^n)Z.
    fn witt_length(&self) -> u64;
}

/// Phase 2 (orphan-closure) — resolver-absent default impl of `Element<H>`.
/// Every accessor returns `H::EMPTY_*` sentinels (for scalar / host-typed
/// returns) or a `'static`-lifetime reference to a sibling `Null*`'s `ABSENT`
/// const (for trait-typed returns).  Downstream provides concrete impls;
/// this stub closes the ontology-derived trait orphan.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NullElement<H: HostTypes> {
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Default for NullElement<H> {
    fn default() -> Self {
        Self {
            _phantom: core::marker::PhantomData,
        }
    }
}
impl<H: HostTypes> NullElement<H> {
    /// Absent-value sentinel. `&Self::ABSENT` gives every trait-typed accessor a `'static`-lifetime reference target.
    pub const ABSENT: NullElement<H> = NullElement {
        _phantom: core::marker::PhantomData,
    };
}
impl<H: HostTypes> Element<H> for NullElement<H> {
    fn length(&self) -> u64 {
        0
    }
    fn addresses(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn digest(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn digest_algorithm(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn canonical_bytes(&self) -> &H::WitnessBytes {
        H::EMPTY_WITNESS_BYTES
    }
    fn witt_length(&self) -> u64 {
        0
    }
}

/// Phase 8 (orphan-closure) — content-addressed handle for `Element<H>`.
///
/// Pairs a [`crate::enforcement::ContentFingerprint`] with a phantom
/// `H` so type-state checks can't mix handles across `HostTypes` impls.
#[derive(Debug)]
pub struct ElementHandle<H: HostTypes> {
    /// Content fingerprint identifying the resolved record.
    pub fingerprint: crate::enforcement::ContentFingerprint,
    _phantom: core::marker::PhantomData<H>,
}
impl<H: HostTypes> Copy for ElementHandle<H> {}
impl<H: HostTypes> Clone for ElementHandle<H> {
    #[inline]
    fn clone(&self) -> Self {
        *self
    }
}
impl<H: HostTypes> PartialEq for ElementHandle<H> {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.fingerprint == other.fingerprint
    }
}
impl<H: HostTypes> Eq for ElementHandle<H> {}
impl<H: HostTypes> core::hash::Hash for ElementHandle<H> {
    #[inline]
    fn hash<S: core::hash::Hasher>(&self, state: &mut S) {
        self.fingerprint.hash(state);
    }
}
impl<H: HostTypes> ElementHandle<H> {
    /// Construct a handle from its content fingerprint.
    #[inline]
    #[must_use]
    pub const fn new(fingerprint: crate::enforcement::ContentFingerprint) -> Self {
        Self {
            fingerprint,
            _phantom: core::marker::PhantomData,
        }
    }
}

/// Phase 8 (orphan-closure) — resolver trait for `Element<H>`.
///
/// Hosts implement this trait to map a handle into a typed record.
/// The default Null stub does not implement this trait — it carries
/// no record. Resolution is the responsibility of the host pipeline.
pub trait ElementResolver<H: HostTypes> {
    /// Resolve a handle into its record. Returns `None` when the
    /// handle does not correspond to known content.
    fn resolve(&self, handle: ElementHandle<H>) -> Option<ElementRecord<H>>;
}

/// Phase 8 (orphan-closure) — typed record for `Element<H>`.
///
/// Carries a field per functional accessor of the trait. Object
/// fields hold `{Range}Handle<H>`; iterate via the Resolved wrapper
/// chain-resolver methods.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct ElementRecord<H: HostTypes> {
    pub length: u64,
    pub addresses: &'static H::HostString,
    pub digest: &'static H::HostString,
    pub digest_algorithm: &'static H::HostString,
    pub canonical_bytes: &'static H::WitnessBytes,
    pub witt_length: u64,
    #[doc(hidden)]
    pub _phantom: core::marker::PhantomData<H>,
}

/// Phase 8 (orphan-closure) — content-addressed wrapper for `Element<H>`.
///
/// Caches the resolver's lookup at construction. Accessors return
/// the cached record's fields when present, falling back to the
/// `Null{Class}<H>` absent sentinels when the resolver returned
/// `None`. Object accessors always return absent sentinels — use
/// the `resolve_{m}` chain methods to descend into sub-records.
pub struct ResolvedElement<'r, R: ElementResolver<H>, H: HostTypes> {
    handle: ElementHandle<H>,
    resolver: &'r R,
    record: Option<ElementRecord<H>>,
}
impl<'r, R: ElementResolver<H>, H: HostTypes> ResolvedElement<'r, R, H> {
    /// Construct the wrapper, eagerly resolving the handle.
    #[inline]
    pub fn new(handle: ElementHandle<H>, resolver: &'r R) -> Self {
        let record = resolver.resolve(handle);
        Self {
            handle,
            resolver,
            record,
        }
    }
    /// The handle this wrapper resolves.
    #[inline]
    #[must_use]
    pub const fn handle(&self) -> ElementHandle<H> {
        self.handle
    }
    /// The resolver supplied at construction.
    #[inline]
    #[must_use]
    pub const fn resolver(&self) -> &'r R {
        self.resolver
    }
    /// The cached record, or `None` when the resolver returned `None`.
    #[inline]
    #[must_use]
    pub const fn record(&self) -> Option<&ElementRecord<H>> {
        self.record.as_ref()
    }
}
impl<'r, R: ElementResolver<H>, H: HostTypes> Element<H> for ResolvedElement<'r, R, H> {
    fn length(&self) -> u64 {
        match &self.record {
            Some(r) => r.length,
            None => 0,
        }
    }
    fn addresses(&self) -> &H::HostString {
        H::EMPTY_HOST_STRING
    }
    fn digest(&self) -> &H::HostString {
        match &self.record {
            Some(r) => r.digest,
            None => H::EMPTY_HOST_STRING,
        }
    }
    fn digest_algorithm(&self) -> &H::HostString {
        match &self.record {
            Some(r) => r.digest_algorithm,
            None => H::EMPTY_HOST_STRING,
        }
    }
    fn canonical_bytes(&self) -> &H::WitnessBytes {
        match &self.record {
            Some(r) => r.canonical_bytes,
            None => H::EMPTY_WITNESS_BYTES,
        }
    }
    fn witt_length(&self) -> u64 {
        match &self.record {
            Some(r) => r.witt_length,
            None => 0,
        }
    }
}