Module provenance 

PROV-O provenance attribution for message envelopes.

Per docs/superpowers/specs/2026-04-17-v1.1-vyngraph-gaps.md section 3.4, this module provides optional per-message attribution metadata for NSAI (neuro-symbolic AI) reasoning chains such as VynGraph audit workloads.

Overview

The full W3C PROV-O vocabulary is large; v1.1 supports the eight core relations that cover 95%+ of NSAI reasoning chains:

Relation	Types	Example
wasAttributedTo	Entity -> Agent	fraud alert attributed to fraud_triangle
wasGeneratedBy	Entity -> Activity	consolidated balance generated by consolidation
wasDerivedFrom	Entity -> Entity	source-trace lineage for audit evidence
used	Activity -> Entity	SoD check used journal entries
wasInformedBy	Activity -> Activity	going-concern informed by cash-flow analysis
wasAssociatedWith	Activity -> Agent	LLM generation associated with auditor prompt
actedOnBehalfOf	Agent -> Agent	assistant acted on behalf of partner
Plan subtype	n/a	audit programs as plans

Qualified relations (qualifiedAttribution, etc.) are deferred to v1.5 - HLC already provides the temporal qualification v1.1 needs.

Design

• Zero cost when unused: MessageEnvelope::provenance is Option<_>.
• 4 inline relation slots cover the common case; overflow spills to an off-band record referenced by overflow_ref.
• Plan is an Entity subclass (matches PROV-O spec) tracked via plan_id.
• All identifiers are u64; the caller (VynGraph) owns the ID namespace.

Example

use ringkernel_core::provenance::{
    ProvNodeType, ProvRelationKind, ProvenanceBuilder,
};
use ringkernel_core::hlc::HlcTimestamp;

// IDs are u64 — caller (e.g., VynGraph) owns the ID namespace
const FRAUD_ALERT_ID: u64 = 0xDEAD_BEEF_0001;
const FRAUD_TRIANGLE_AGENT: u64 = 0xA6E0_7751_0002;
const GAAP_RUN_ACTIVITY: u64 = 0xAC71_7170_0003;

let hdr = ProvenanceBuilder::new(ProvNodeType::Entity, FRAUD_ALERT_ID)
    .with_timestamp(HlcTimestamp::now(1))
    .with_relation(ProvRelationKind::WasAttributedTo, FRAUD_TRIANGLE_AGENT)
    .with_relation(ProvRelationKind::WasGeneratedBy, GAAP_RUN_ACTIVITY)
    .build()
    .unwrap();
assert_eq!(hdr.relation_count(), 2);

Structs

ArchivedProvRelation

An archived ProvRelation

ArchivedProvenanceHeader

An archived ProvenanceHeader

ProvRelation

A single PROV-O relation edge (kind + target node ID).

ProvRelationResolver

The resolver for an archived ProvRelation

ProvenanceBuilder

Builder for ProvenanceHeader.

ProvenanceHeader

PROV-O attribution metadata attached to a message envelope.

ProvenanceHeaderResolver

The resolver for an archived ProvenanceHeader

Enums

ArchivedProvNodeType

An archived ProvNodeType

ArchivedProvRelationKind

An archived ProvRelationKind

ProvNodeType

Classification of a PROV-O node.

ProvNodeTypeResolver

The resolver for an archived ProvNodeType

ProvRelationKind

PROV-O relation kind (edge label).

ProvRelationKindResolver

The resolver for an archived ProvRelationKind

ProvenanceError

Errors raised when constructing or validating provenance headers.

Constants

INLINE_RELATION_SLOTS

Maximum number of relations that fit inline (without overflow spill).

MAX_CHAIN_DEPTH

Maximum chain depth when walking wasDerivedFrom / wasInformedBy relations during validation. Guards against pathological graphs.

Functions

validate_chain

Walk a derivation / informing chain to validate bounded depth and the absence of cycles.