Struct KnowledgeObject 

pub struct KnowledgeObject { /* private fields */ }

The atomic unit of the Knowledge Fabric.

A Knowledge Object co-locates content, relationships, embeddings, temporal metadata, and provenance into a single, content-addressed entity. This co-location enables the fused query execution pipeline that delivers 30–50× latency improvements over disaggregated architectures.

Invariants

1. oid == BLAKE3(canonical_bytes(payload, edges, embeddings)) — the OID is always consistent with the object’s content.
2. temporal.system_time is monotonically increasing for successive versions of the same logical entity.
3. Edges form a DAG for DerivedFrom and Succeeds kinds (no cycles).
4. Embedding dimensions match the declared space dimensionality.

Thread Safety

KnowledgeObject is Send + Sync (all fields are owned or Arc-wrapped). Concurrent mutation should go through the MVCC layer — objects themselves are treated as immutable values (copy-on-write semantics via content addressing).

Implementations

impl KnowledgeObject

pub fn oid(&self) -> ObjectId

The content-addressed object identity.

pub fn kind(&self) -> &ObjectKind

The object’s classification.

pub fn payload(&self) -> &SochValue

The data payload.

pub fn payload_mut(&mut self) -> &mut SochValue

Mutable access to the payload (will invalidate OID — call recompute_oid() after).

pub fn edges(&self) -> &[Edge]

All outgoing edges.

pub fn edges_of_kind(&self, kind: &EdgeKind) -> Vec<&Edge>

Edges filtered by kind.

pub fn edges_valid_at(&self, time: u64) -> Vec<&Edge>

Edges valid at a given time.

pub fn embedding(&self, space: &str) -> Option<&EmbeddingSpace>

Get an embedding by space name.

pub fn embeddings(&self) -> &HashMap<String, EmbeddingSpace>

All embedding spaces.

pub fn primary_embedding(&self) -> Option<&[f32]>

The default/primary embedding vector (in the “semantic” space).

pub fn temporal(&self) -> &BitemporalCoord

The bitemporal coordinate.

pub fn set_temporal(&mut self, coord: BitemporalCoord)

Set the bitemporal coordinate (e.g., to assign HLC system_time on write).

Note: This does NOT change the OID. Temporal coordinates are metadata, not part of the content-addressed identity.

pub fn provenance(&self) -> &Provenance

The derivation provenance.

pub fn namespace(&self) -> Option<&str>

The namespace (for multi-tenant isolation).

pub fn tags(&self) -> &[String]

Tags for categorical filtering.

pub fn has_tag(&self, tag: &str) -> bool

Check if this object has a specific tag.

pub fn valid_at(&self, valid_time: u64) -> bool

Is this object valid at the given valid time?

pub fn known_at(&self, system_time: u64) -> bool

Was this object known to the system at the given system time?

pub fn visible_at(&self, system_time: u64, valid_time: u64) -> bool

Combined bitemporal visibility check.

pub fn is_current(&self) -> bool

Is this the current version (valid_to == MAX)?

pub fn attribute(&self, key: &str) -> Option<&SochValue>

Get a named attribute from the payload (assumes payload is SochValue::Object).

pub fn text_attribute(&self, key: &str) -> Option<&str>

Get a text attribute.

pub fn int_attribute(&self, key: &str) -> Option<i64>

Get an integer attribute.

pub fn recompute_oid(&mut self)

Recompute the OID from the current content. Must be called after any mutation to maintain the content-addressing invariant.

pub fn verify_oid(&self) -> bool

Verify that the stored OID matches the current content.

impl KnowledgeObject

pub fn to_bytes(&self) -> Result<Vec<u8>, KnowledgeObjectError>

Serialize this Knowledge Object to compact binary format. Uses serde_json for reliable HashMap serialization.

pub fn from_bytes(bytes: &[u8]) -> Result<Self, KnowledgeObjectError>

Deserialize a Knowledge Object from binary format.

pub fn estimated_size(&self) -> usize

Estimated memory footprint of this object (for memory budgeting).

pub fn to_compressed_bytes( &self, mode: CompressionMode, ) -> Result<Vec<u8>, KnowledgeObjectError>

Serialize with per-object compression.

Wire format: [tag: u8] [original_len: u32 LE] [payload...]

• Tag 0 (None): payload is raw JSON (original_len == payload.len()).
• Tag 1 (Lz4): payload is LZ4-block-compressed JSON.
• Tag 2 (Zstd): payload is ZSTD-compressed JSON.

Falls back to uncompressed if compressed output >= original size.

pub fn from_compressed_bytes(bytes: &[u8]) -> Result<Self, KnowledgeObjectError>

Deserialize from compressed wire format (auto-detects compression).

The 1-byte tag determines the decompression algorithm.

pub fn compression_ratio( &self, mode: CompressionMode, ) -> Result<f64, KnowledgeObjectError>

Returns the compression ratio for a given mode (compressed_size / original_size). Values < 1.0 indicate space savings.

Trait Implementations

impl Clone for KnowledgeObject

fn clone(&self) -> KnowledgeObject

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KnowledgeObject

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for KnowledgeObject

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for KnowledgeObject

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

Formats the value using the given formatter.

impl Eq for KnowledgeObject

impl Hash for KnowledgeObject

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for KnowledgeObject

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for KnowledgeObject

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

where __S: Serializer,

Serialize this value into the given Serde serializer.