Struct Provenance 

pub struct Provenance {
    pub timestamp: SystemTime,
    pub kind: ProvenanceKind,
    pub entity: Option<String>,
    pub actor: Actor,
    pub client: Option<ClientId>,
    pub note: Option<String>,
    pub logical_operation_id: Option<String>,
    pub role: Role,
}

One mutation event in a mem’s provenance log.

Constructed at the engine boundary (one per MCP mutating tool, one per CLI mutation, one per drift-flush) and handed to the backend via crate::backend::MemBackend::append_provenance. Read back out via crate::backend::MemBackend::read_provenance for memstead_changes_since.

The folder backend persists this as a JSONL line under .memstead/changes.jsonl; the git-branch backend persists it as part of the commit-message trailer block (timestamp / kind / entity ride the commit metadata). The persistence form differs per backend, the in-memory record does not.

Fields

timestamp: SystemTime

kind: ProvenanceKind

entity: Option<String>

Mem-relative entity id (mem:slug), or None for batch mutations that touch multiple entities.

actor: Actor

client: Option<ClientId>

note: Option<String>

Agent-authored one-sentence provenance note. Whitespace-only values are normalised to None at construction; callers that want an empty note pass None.

logical_operation_id: Option<String>

Correlation id that ties every commit produced by a single logical operation (notably a multi-mem memstead_rename) to one another. Some(id) on every commit a single logical call produced; None on legacy or single-call mutations that don’t participate in correlation. Consumers that don’t know the field continue working — it’s purely additive. Single-mem mutations may carry an id too (a logical-op with one commit), or None — both are valid wire shapes.

role: Role

The caller-declared role (agent-trust plan 13). Unspecified records as absence on both backends (no trailer, no ledger field) — old records read back as Unspecified.

Implementations

impl Provenance

pub fn new( timestamp: SystemTime, kind: ProvenanceKind, entity: Option<String>, actor: Actor, client: Option<ClientId>, note: Option<String>, ) -> Self

Build a record, normalising a whitespace-only note to None. Callers that already have a normalised Option<String> may set the field directly. logical_operation_id defaults to None; callers that need to tag a multi-commit logical operation use Self::with_logical_operation_id.

pub fn with_role(self, role: Role) -> Self

Builder: attach the caller-declared role (agent-trust plan 13).

pub fn with_logical_operation_id(self, id: String) -> Self

Builder: attach a correlation id so multiple commits produced by a single logical operation can be linked at read time.

Trait Implementations

impl Clone for Provenance

fn clone(&self) -> Provenance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Provenance

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

Formats the value using the given formatter.