Arxi Decision Gate Asset Core
Docs
Arxi Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Arxi Storage Architecture

Audience: Engineers changing persistence logic, query semantics, schema, or storage backends.

Table of Contents

  1. Executive Overview
  2. Store Trait Contracts
  3. In-Memory Backend
  4. SQLite Backend
  5. SQLite Schema and Indexing
  6. Chain Continuity Enforcement
  7. Query and Pagination Semantics
  8. Corruption and Error Handling
  9. File-by-File Cross Reference

Executive Overview

arxi-store provides the persistence abstraction and two concrete backends:

  • InMemoryStore for deterministic testing and local execution,
  • SqliteStore for durable operation with WAL and transactional checks.

Both implement shared trait contracts for envelope, attachment, and segment operations. F:crates/arxi-store/src/lib.rs L11-L37 F:crates/arxi-store/src/lib.rs L49-L71

Store Trait Contracts

Storage contract is expressed as three async traits:

  • EnvelopeStore: append/get/query/chain-head/segment-envelopes,
  • AttachmentStore: put/get/exists for content-addressed blobs,
  • SegmentStore: create/seal/list/get metadata and genesis.

Core invariants include append-only behavior, chain continuity checks, and sealed-segment immutability. Segment creation is fail-closed: stores reject a new segment when another open segment already exists or when the segment ID already exists. F:crates/arxi-store/src/traits.rs L43-L101 F:crates/arxi-store/src/traits.rs L107-L138 F:crates/arxi-store/src/traits.rs L144-L206

In-Memory Backend

InMemoryStore uses lock-protected maps and vectors, preserving invariant checks but without crash consistency guarantees. F:crates/arxi-store/src/memory.rs L12-L16

Behavior highlights:

  • validates segment state and chain continuity on append,
  • maintains first/last envelope IDs and chain head updates,
  • enforces single-open-segment and no-duplicate-segment-ID creation rules,
  • supports deterministic segment listing by created_at,
  • enforces deterministic envelope query ordering by segment_id then sequence.

F:crates/arxi-store/src/memory.rs L124-L180 F:crates/arxi-store/src/memory.rs L317-L407

SQLite Backend

SqliteStore routes all DB operations through a dedicated connection thread (SqliteConnection) to preserve single-writer semantics safely across async callers. F:crates/arxi-store/src/sqlite/mod.rs L12-L22 F:crates/arxi-store/src/sqlite/connection.rs L12-L21

SqliteConnection::execute uses bounded sync_channel + oneshot channels to bridge async code with sync rusqlite operations. Queue admission is explicit: enqueue saturation fails closed with StoreError::ConcurrencyConflict rather than allowing unbounded in-memory work growth. F:crates/arxi-store/src/sqlite/connection.rs L42-L136 F:crates/arxi-store/src/sqlite/connection.rs L167-L222

SqliteStore additionally exposes typed metadata helpers over store_meta (get_meta, set_meta, set_meta_batch) for deterministic runtime state such as signer-key rotation idempotence markers. F:crates/arxi-store/src/sqlite/mod.rs

SQLite Schema and Indexing

Initialization enables:

  • WAL mode,
  • foreign keys,
  • schema metadata table,
  • normalized segments, envelopes, attachments, and junction tables,
  • indexes for deterministic envelope/segment query patterns.

F:crates/arxi-store/src/sqlite/schema.rs L111-L144 F:crates/arxi-store/src/sqlite/schema.rs L43-L105

Chain Continuity Enforcement

Both backends enforce append-time chain validation using expected chain-head recomputation and constant-time comparison.

In-memory append validation: F:crates/arxi-store/src/memory.rs L140-L158

SQLite append validation is transaction-scoped:

  1. verify segment exists and is open,
  2. recompute expected chain hash,
  3. reject mismatch,
  4. insert envelope + envelope-attachment rows,
  5. update segment metadata atomically.

F:crates/arxi-store/src/sqlite/envelope_ops.rs L42-L141

Query and Pagination Semantics

Envelope queries support multi-field filtering plus cursor continuation and limit. SQLite query order is ORDER BY segment_id, sequence; segment-envelope queries order by sequence ASC.

F:crates/arxi-store/src/sqlite/envelope_ops.rs L167-L280 F:crates/arxi-store/src/sqlite/envelope_ops.rs L306-L347

Segment listing supports status/time/id filters and orders by created_at ASC. F:crates/arxi-store/src/sqlite/segment_ops.rs L148-L245

Corruption and Error Handling

StoreError explicitly differentiates integrity breaks, not-found cases, concurrency conflicts, backend failures, and corruption detection. F:crates/arxi-store/src/error.rs L36-L103

SQLite segment parsing treats invalid DB values as corruption (invalid UUID, unknown status, unknown hash algorithm, invalid timestamps). F:crates/arxi-store/src/sqlite/segment_ops.rs L336-L416

System tests now validate fail-closed behavior when persisted SQLite rows are tampered with invalid segment UUID/genesis data between CLI operations. F:system-tests/tests/suites/persistence.rs L375-L468

File-by-File Cross Reference

AreaFileNotes
Storage contractscrates/arxi-store/src/traits.rsCanonical storage trait invariants.
Segment typescrates/arxi-store/src/types.rsSegment metadata and filter shapes.
In-memory backendcrates/arxi-store/src/memory.rsDeterministic map-based implementation.
SQLite facadecrates/arxi-store/src/sqlite/mod.rsStore construction and backend composition.
SQLite metadata helperscrates/arxi-store/src/sqlite/mod.rsstore_meta read/write helpers for runtime state persistence.
SQLite bridgecrates/arxi-store/src/sqlite/connection.rsDedicated thread async bridge.
SQLite schemacrates/arxi-store/src/sqlite/schema.rsDDL, indexes, schema versioning.
Envelope SQL opscrates/arxi-store/src/sqlite/envelope_ops.rsTransactional append and filter query logic.
Segment SQL opscrates/arxi-store/src/sqlite/segment_ops.rsSegment lifecycle and metadata decoding.
Attachment SQL opscrates/arxi-store/src/sqlite/attachment_ops.rsContent-addressed put/get/exists semantics.
Error taxonomycrates/arxi-store/src/error.rsTyped storage failure model.