Trait ExperienceStore 

pub trait ExperienceStore: Send + Sync {
    // Required methods
    fn append_event(
        &self,
        event: ExperienceEventEnvelope,
    ) -> Result<(), ExperienceStoreError>;
    fn query_events(
        &self,
        query: &EventQuery,
    ) -> Result<Vec<ExperienceEventEnvelope>, ExperienceStoreError>;
    fn write_artifact_state_transition(
        &self,
        artifact_id: &ArtifactId,
        artifact_kind: ArtifactKind,
        event: LifecycleEvent,
    ) -> Result<(), ExperienceStoreError>;
    fn get_trace_link(
        &self,
        trace_link_id: &TraceLinkId,
    ) -> Result<Option<ReplayTrace>, ExperienceStoreError>;

    // Provided methods
    fn append_events(
        &self,
        events: &[ExperienceEventEnvelope],
    ) -> Result<(), ExperienceStoreError> { ... }
    fn append_user_event(
        &self,
        _event: UserExperienceEventEnvelope,
    ) -> Result<(), ExperienceStoreError> { ... }
    fn query_records(
        &self,
        query: &EventQuery,
    ) -> Result<Vec<ExperienceRecord>, ExperienceStoreError> { ... }
}

Experience store trait (append-only ledger boundary).

This is the canonical audit trail interface. Implementations provide append-only event storage and query access for governance, debugging, and downstream analytics.

See [converge_experience] for concrete implementations: InMemoryExperienceStore, SurrealDbExperienceStore, LanceDbExperienceStore.

Required Methods

fn append_event( &self, event: ExperienceEventEnvelope, ) -> Result<(), ExperienceStoreError>

Append a single event.

fn query_events( &self, query: &EventQuery, ) -> Result<Vec<ExperienceEventEnvelope>, ExperienceStoreError>

Query events by tenant/time/kind/etc.

fn write_artifact_state_transition( &self, artifact_id: &ArtifactId, artifact_kind: ArtifactKind, event: LifecycleEvent, ) -> Result<(), ExperienceStoreError>

Write an artifact lifecycle transition event.

fn get_trace_link( &self, trace_link_id: &TraceLinkId, ) -> Result<Option<ReplayTrace>, ExperienceStoreError>

Fetch a trace link by id.

Provided Methods

fn append_events( &self, events: &[ExperienceEventEnvelope], ) -> Result<(), ExperienceStoreError>

Append multiple events (best-effort atomicity per implementation).

fn append_user_event( &self, _event: UserExperienceEventEnvelope, ) -> Result<(), ExperienceStoreError>

Append a single user-side experience event.

Default implementation returns Unsupported. In-process backends override this to record the event in the same ledger as engine events.

fn query_records( &self, query: &EventQuery, ) -> Result<Vec<ExperienceRecord>, ExperienceStoreError>

Query both engine-side and user-side records, ordered by occurrence.

Default implementation lifts engine events through the ExperienceRecord::Engine variant. Backends that store user events override this to interleave both record kinds.

Implementors