Struct SqlitePersistenceStore 

pub struct SqlitePersistenceStore { /* private fields */ }

The SQLite-backed implementation of PersistencePort.

Construct via SqlitePersistenceStore::new(conn) where conn is a fully-initialised rusqlite Connection (PRAGMAs applied, migrations run — use connection::open or connection::open_in_memory).

Implementations

impl SqlitePersistenceStore

pub fn new(conn: Connection) -> Self

Create a store wrapping an already-initialised Connection.

pub fn pending_store(&self) -> SqlitePendingStore

Return a SqlitePendingStore that shares the same SQLite connection.

This is the standard way to construct the pending-adjudication adapter:

let store = SqlitePersistenceStore::new(conn);
let pending = store.pending_store();

Both SqlitePersistenceStore and SqlitePendingStore share the connection Arc, so the pending insert is serialized with the claim transaction by the EngineHandle write lock — not by a shared rusqlite transaction.

Trait Implementations

impl PersistencePort for SqlitePersistenceStore

fn begin_atomic( &self, agent_id: &AgentId, ) -> Result<SqliteTxn, SqliteStoreError>

Open an explicit BEGIN DEFERRED transaction scoped to agent_id.

The connection is moved into the returned SqliteTxn. Calling begin_atomic again before commit/rollback returns SqliteStoreError::TxnAlreadyOpen.

fn commit(&self, txn: SqliteTxn) -> Result<(), SqliteStoreError>

Commit the transaction and return the connection to the store.

fn rollback(&self, txn: SqliteTxn) -> Result<(), SqliteStoreError>

Rollback the transaction and return the connection to the store. On rollback all rows appended within the txn are discarded (all-or-nothing atomicity).

fn append_claim( &self, txn: &mut SqliteTxn, claim: &Claim, ) -> Result<ClaimRef, SqliteStoreError>

Append a claim row within the open transaction.

Column mapping (§5):

• claim_id ← claim.claim_ref().0 (UUID → TEXT)
• agent_id ← claim.agent_id().0
• provenance_label ← provenance_to_str(claim.provenance()) (NOT NULL; bi-temporal provenance column)
• nearest_external_anchor_id ← ExternalAnchor.nearest_external_anchor (nullable)
• derived_from ← JSON array of ClaimRef UUIDs

fn append_validity_assertion( &self, txn: &mut SqliteTxn, assertion: &ValidityAssertion, ) -> Result<(), SqliteStoreError>

Append a validity assertion row (Bound or Reopen) within the open transaction.

fn append_ledger_entry( &self, txn: &mut SqliteTxn, entry: &LedgerEntry, ) -> Result<(), SqliteStoreError>

Append a ledger entry row within the open transaction.

fn append_claim_edge( &self, txn: &mut SqliteTxn, edge: &ClaimEdge, ) -> Result<(), SqliteStoreError>

Append a claim edge row within the open transaction.

fn load_subject_line( &self, agent_id: &AgentId, subject: &str, predicate: &str, ) -> Result<Vec<Claim>, SqliteStoreError>

Load all claims on the given (agent_id, subject, predicate) subject-line, ordered by tx_time ASC (oldest first — callers fold in tx_time order).

Uses idx_claims_subject_line covering index (§5).

fn load_claim( &self, agent_id: &AgentId, claim_ref: &ClaimRef, ) -> Result<Option<Claim>, SqliteStoreError>

Load a single claim by its ClaimRef. Returns None if not found.

fn load_validity_assertions_for( &self, agent_id: &AgentId, claim_ref: &ClaimRef, ) -> Result<Vec<ValidityAssertion>, SqliteStoreError>

Load all validity assertions targeting a claim, ordered by asserted_at ASC.

Uses idx_validity_assertions_target index (§5).

fn load_ledger( &self, agent_id: &AgentId, from: Option<&TransactionTime>, limit: usize, ) -> Result<Vec<LedgerEntry>, SqliteStoreError>

Load ledger entries for an agent, optionally starting from from (inclusive), limited to limit rows, ordered by recorded_at ASC.

Uses idx_ledger_agent_time index (§5). from = None returns from the beginning.

fn load_ledger_for_claims( &self, agent_id: &AgentId, claim_refs: &[ClaimRef], ) -> Result<Vec<LedgerEntry>, SqliteStoreError>

Load ALL ledger entries for the given claim refs, no row cap.

SQLite limits bound parameters to ~999 per statement (SQLITE_LIMIT_VARIABLE_NUMBER). Chunks the IN list into batches of 900 and concatenates results so this method is safe for any slice size.

fn load_edges_for( &self, agent_id: &AgentId, claim_ref: &ClaimRef, ) -> Result<Vec<ClaimEdge>, SqliteStoreError>

Load all edges where claim_ref is either the from or to end, for this agent. Ordered by created_at ASC (deterministic cascade — required by convention).

Uses idx_edges_from and idx_edges_to indexes (§5).

fn load_injected_claims( &self, agent_id: &AgentId, ) -> Result<Vec<ClaimRef>, SqliteStoreError>

Load the set of ClaimRefs served as injected claims for this agent (used by the Amplification Guard).

Scans ledger_entries for event_kind = 'ServedAsInjected' and returns the distinct set of claim IDs, ordered by recorded_at ASC.

fn load_lineage( &self, agent_id: &AgentId, claim_ref: &ClaimRef, ) -> Result<Vec<ClaimEdge>, SqliteStoreError>

Recursive CTE lineage traversal.

Traverses DerivedFrom edges upward (from claim_ref to its ancestors), returning all ClaimEdge rows in the lineage sub-graph, ordered by depth (shallowest first, then by created_at ASC within the same depth level).

The CTE is bounded by max_depth = 64 to prevent runaway on pathological graphs.

type Transaction = SqliteTxn

type Error = SqliteStoreError

fn requires_global_write_serialization(&self) -> bool

Whether the store requires a global write serialization lock across all agent_ids.

impl Send for SqlitePersistenceStore

impl Sync for SqlitePersistenceStore