feat(core): add PROV-O provenance metadata (v1.1)

Per spec section 3.4, add optional ProvenanceHeader to MessageEnvelope
with 8 core PROV-O relations for NSAI reasoning chain attribution
(VynGraph integration).

ProvenanceHeader:
- 4 inline relation slots + overflow_ref for overflow
- HLC timestamp for PROV event time
- Optional plan_id (Plan is PROV-O Entity subclass)
- 136 bytes when present, 1 byte (None discriminant) when absent
- Zero cost for messages that don't opt in

PROV-O relations supported:
- wasAttributedTo (Entity → Agent)
- wasGeneratedBy (Entity → Activity)
- wasDerivedFrom (Entity → Entity)
- used (Activity → Entity)
- wasInformedBy (Activity → Activity)
- wasAssociatedWith (Activity → Agent)
- actedOnBehalfOf (Agent → Agent)
- Plan entity subtype

Builder API: ProvenanceBuilder::new(node_type, node_id).with_relation()...
Validation: node_id != 0, no self-loops, type-correct relations,
chain depth bounded (256), cycle detection.

20 unit tests for builder, validation, chain walking, enum roundtrips.
676 existing tests still pass (no regressions).

HlcTimestamp gains rkyv derives for embedding in provenance header.
MessageEnvelope constructors default to provenance: None.

Qualified relations (qualifiedAttribution etc.) deferred to v1.5.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mivertowski

Cargo.lock

@@ -607,6 +607,7 @@ mod tests {
         let envelope = MessageEnvelope {
             header,
             payload: vec![],
+            provenance: None,
         };
 
         let result = dispatcher.dispatch(envelope).await;

crates/ringkernel-core/src/dispatcher.rs

@@ -285,6 +285,7 @@ mod tests {
         MessageEnvelope {
             header: MessageHeader::new(1, 0, 1, 64, HlcTimestamp::now(1)),
             payload: vec![42u8; 64],
+            provenance: None,
         }
     }
 

crates/ringkernel-core/src/dlq.rs

@@ -40,8 +40,22 @@ pub const MAX_CLOCK_SKEW_MS: u64 = 60_000; // 1 minute
 ///
 /// This struct is 24 bytes and cache-line friendly.
 #[derive(
-    Debug, Clone, Copy, PartialEq, Eq, Hash, AsBytes, FromBytes, FromZeroes, Pod, Zeroable,
+    Debug,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    Hash,
+    AsBytes,
+    FromBytes,
+    FromZeroes,
+    Pod,
+    Zeroable,
+    rkyv::Archive,
+    rkyv::Serialize,
+    rkyv::Deserialize,
 )]
+#[archive(compare(PartialEq))]
 #[repr(C, align(8))]
 pub struct HlcTimestamp {
     /// Physical time component (microseconds since UNIX epoch).

crates/ringkernel-core/src/hlc.rs

@@ -70,6 +70,7 @@ pub mod message;
 pub mod multi_gpu;
 pub mod observability;
 pub mod persistent_message;
+pub mod provenance;
 pub mod pubsub;
 pub mod queue;
 pub mod reduction;
@@ -176,6 +177,10 @@ pub mod prelude {
         message_flags, DispatchTable, HandlerRegistration, PersistentMessage,
         MAX_INLINE_PAYLOAD_SIZE,
     };
+    pub use crate::provenance::{
+        validate_chain, ProvNodeType, ProvRelation, ProvRelationKind, ProvenanceBuilder,
+        ProvenanceError, ProvenanceHeader, INLINE_RELATION_SLOTS, MAX_CHAIN_DEPTH,
+    };
     pub use crate::pubsub::{PubSubBroker, PubSubBuilder, Publication, QoS, Subscription, Topic};
     pub use crate::queue::*;
     pub use crate::reduction::{
@@ -281,6 +286,10 @@ pub use error::{Result, RingKernelError};
 pub use hlc::HlcTimestamp;
 pub use memory::{DeviceMemory, GpuBuffer, MemoryPool, PinnedMemory};
 pub use message::{priority, MessageHeader, MessageId, Priority, RingMessage};
+pub use provenance::{
+    ProvNodeType, ProvRelation, ProvRelationKind, ProvenanceBuilder, ProvenanceError,
+    ProvenanceHeader,
+};
 pub use queue::{MessageQueue, QueueStats};
 pub use runtime::{
     Backend, KernelHandle, KernelId, KernelState, KernelStatus, LaunchOptions, RingKernelRuntime,

crates/ringkernel-core/src/lib.rs

@@ -8,6 +8,7 @@ use rkyv::{Archive, Deserialize, Serialize};
 use zerocopy::{AsBytes, FromBytes, FromZeroes};
 
 use crate::hlc::HlcTimestamp;
+use crate::provenance::ProvenanceHeader;
 
 /// Unique message identifier.
 #[derive(
@@ -372,12 +373,28 @@ pub trait RingMessage: Send + Sync + 'static {
 }
 
 /// Envelope containing header and serialized payload.
+///
+/// The optional `provenance` slot carries PROV-O attribution metadata for
+/// NSAI reasoning chains (see [`crate::provenance`]). When `None`, the field
+/// is a single discriminant byte - zero cost for the common case. When
+/// populated, it adds a fixed-size [`ProvenanceHeader`] (see that type for
+/// size details).
+///
+/// The `provenance` field is *not* included in the legacy
+/// [`MessageEnvelope::to_bytes`] / [`MessageEnvelope::from_bytes`] wire format,
+/// which is defined by `MessageHeader` + raw payload for backwards
+/// compatibility. Provenance travels separately (e.g. as part of rkyv-encoded
+/// envelope transfer on GPU) or is reattached by the router.
 #[derive(Debug, Clone)]
 pub struct MessageEnvelope {
     /// Message header.
     pub header: MessageHeader,
     /// Serialized payload.
     pub payload: Vec<u8>,
+    /// Optional PROV-O attribution metadata. Defaults to `None`; only
+    /// populated when the message participates in an audited reasoning
+    /// chain (e.g. VynGraph NSAI pipelines).
+    pub provenance: Option<ProvenanceHeader>,
 }
 
 impl MessageEnvelope {
@@ -399,7 +416,11 @@ impl MessageEnvelope {
         .with_correlation(message.correlation_id())
         .with_priority(message.priority());
 
-        Self { header, payload }
+        Self {
+            header,
+            payload,
+            provenance: None,
+        }
     }
 
     /// Get total size (header + payload).
@@ -408,6 +429,10 @@ impl MessageEnvelope {
     }
 
     /// Serialize to contiguous bytes.
+    ///
+    /// NOTE: the provenance metadata is intentionally *not* serialised here.
+    /// This method keeps the historical wire format unchanged; provenance is
+    /// transported out-of-band or via rkyv-encoded transfer.
     pub fn to_bytes(&self) -> Vec<u8> {
         let mut bytes = Vec::with_capacity(self.total_size());
         bytes.extend_from_slice(self.header.as_bytes());
@@ -416,6 +441,9 @@ impl MessageEnvelope {
     }
 
     /// Deserialize from bytes.
+    ///
+    /// Reconstructs an envelope with `provenance: None`. Callers that need
+    /// provenance must reattach it via [`MessageEnvelope::with_provenance`].
     pub fn from_bytes(bytes: &[u8]) -> crate::error::Result<Self> {
         if bytes.len() < std::mem::size_of::<MessageHeader>() {
             return Err(crate::error::RingKernelError::DeserializationError(
@@ -445,7 +473,11 @@ impl MessageEnvelope {
 
         let payload = bytes[payload_start..payload_end].to_vec();
 
-        Ok(Self { header, payload })
+        Ok(Self {
+            header,
+            payload,
+            provenance: None,
+        })
     }
 
     /// Create an empty envelope (for testing).
@@ -454,8 +486,22 @@ impl MessageEnvelope {
         Self {
             header,
             payload: Vec::new(),
+            provenance: None,
         }
     }
+
+    /// Attach a PROV-O provenance header (builder-style).
+    pub fn with_provenance(mut self, provenance: ProvenanceHeader) -> Self {
+        self.provenance = Some(provenance);
+        self
+    }
+
+    /// Strip provenance (builder-style). Useful when routing a message into
+    /// an untrusted tenant boundary where attribution must not leak.
+    pub fn without_provenance(mut self) -> Self {
+        self.provenance = None;
+        self
+    }
 }
 
 #[cfg(test)]
@@ -499,12 +545,39 @@ mod tests {
         let envelope = MessageEnvelope {
             header,
             payload: vec![1, 2, 3, 4, 5, 6, 7, 8],
+            provenance: None,
         };
 
         let bytes = envelope.to_bytes();
         let restored = MessageEnvelope::from_bytes(&bytes).unwrap();
 
         assert_eq!(envelope.header.message_type, restored.header.message_type);
         assert_eq!(envelope.payload, restored.payload);
+        // Provenance is intentionally not round-tripped through the legacy
+        // wire format; restored envelopes carry `None` until reattached.
+        assert!(restored.provenance.is_none());
+    }
+
+    #[test]
+    fn test_envelope_with_provenance() {
+        use crate::provenance::{ProvNodeType, ProvRelationKind, ProvenanceBuilder};
+
+        let hdr = ProvenanceBuilder::new(ProvNodeType::Entity, 0x42)
+            .with_relation(ProvRelationKind::WasAttributedTo, 0x7)
+            .build()
+            .unwrap();
+
+        let envelope = MessageEnvelope::empty(0, 1, HlcTimestamp::now(1)).with_provenance(hdr);
+        assert!(envelope.provenance.is_some());
+        assert_eq!(envelope.provenance.unwrap().node_id, 0x42);
+
+        let stripped = envelope.without_provenance();
+        assert!(stripped.provenance.is_none());
+    }
+
+    #[test]
+    fn test_envelope_default_has_no_provenance() {
+        let envelope = MessageEnvelope::empty(0, 1, HlcTimestamp::zero());
+        assert!(envelope.provenance.is_none());
     }
 }