klieo-provenance 3.4.0

Append-only Merkle hash chain with signed evidence bundles for agent and audit provenance.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

//! Repository port for persisting and querying provenance chains.

use async_trait::async_trait;
use chrono::{DateTime, Utc};

use crate::chain::{ChainEntry, ProvenanceEvent};
use crate::error::ProvenanceError;

/// Persistent storage port for a per-scope append-only chain.
#[async_trait]
pub trait ProvenanceRepository: Send + Sync {
    /// Append a new entry to the chain identified by `scope`.
    async fn append(
        &self,
        scope: &str,
        event: ProvenanceEvent,
    ) -> Result<ChainEntry, ProvenanceError>;

    /// Current head entry (highest sequence) for the scope.
    async fn head(&self, scope: &str) -> Result<Option<ChainEntry>, ProvenanceError>;

    /// Range query by sequence number, inclusive on both ends.
    ///
    /// **Unbounded:** returns every matching entry — there is no `LIMIT`.
    /// Callers MUST bound the range themselves on long-lived chains. A
    /// paginated `list_range_limited` variant will be added (additively)
    /// alongside the first production caller that needs it (see ADR-052).
    async fn list_range(
        &self,
        scope: &str,
        from_sequence: u64,
        to_sequence: u64,
    ) -> Result<Vec<ChainEntry>, ProvenanceError>;

    /// Range query by recorded-at timestamp, inclusive on both ends.
    ///
    /// **Unbounded:** returns every matching entry — there is no `LIMIT`.
    /// Bound the time window yourself on long-lived chains; a paginated
    /// variant lands with the first production caller (see ADR-052).
    async fn list_by_time(
        &self,
        scope: &str,
        from: DateTime<Utc>,
        to: DateTime<Utc>,
    ) -> Result<Vec<ChainEntry>, ProvenanceError>;
}