Arquitectura d’emmagatzematge Arxi

Audience: Engineers changing persistence logic, query semantics, schema, Audiència: Enginyers que canvien la lògica de persistència, la semàntica de consultes, l’esquema o els backends d’emmagatzematge.

Taula de continguts

Visió Executiva
Contractes de Trait de Botiga
Backend en memòria
SQLite Backend
Esquema SQLite i Indexació
Aplicació de la Continuïtat de la Cadena
Semàntica de Consulta i Paginació
Corrupció i Gestió d’Errors
File per Fitxer Referència Creuada

Executive Overview

arxi-store proporciona l’abstracció de persistència i dos backend concrets:

InMemoryStore per a proves deterministes i execució local,
SqliteStore per a l’operació durable amb WAL i comprovacions transaccionals.

Ambdós implementen contractes de trait compartits per a operacions d’envelop, adjunt i segment. F:crates/arxi-store/src/lib.rs L11-L37 F:crates/arxi-store/src/lib.rs L49-L71

Contractes de Trait de Botiga

El contracte d’emmagatzematge s’expressa com tres característiques asíncrones:

EnvelopeStore: afegir/obtenir/consultar/cadenar-cap/segmentar-envelopes,
AttachmentStore: posar/obtenir/existir per blobs adreçats al contingut,
SegmentStore: crear/sellar/llistar/obtenir metadades i gènesi.

Les invariants principals inclouen un comportament d’addició només, comprovacions de continuïtat de la cadena i immutabilitat de segments segellats. La creació de segments és tancada per fallades: les botigues rebutgen un nou segment quan ja existeix un altre segment obert o quan ja existeix l’ID del segment. 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

Backend en memòria

InMemoryStore utilitza mapes i vectors protegits per bloqueig, preservant les comprovacions d’invariància però sense garanties de consistència en cas de fallada. F:crates/arxi-store/src/memory.rs L12-L16

Aspectes destacats del comportament:

valida l’estat del segment i la continuïtat de la cadena en afegir,
manté les ID d’envelopes de primer/últim i les actualitzacions del cap de cadena,
aplica regles de creació de segment únic obert i sense ID de segment duplicat,
suporta la llista de segments determinista per created_at,
aplica un ordre de consulta d’envelopes determinista per segment_id i després per seqüència.

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

SQLite Backend

SqliteStore dirigeix totes les operacions de la base de dades a través d’un fil de connexió dedicat (SqliteConnection) per preservar de manera segura la semàntica de l’escriptor únic entre els cridadors asíncrons. F:crates/arxi-store/src/sqlite/mod.rs L12-L22 F:crates/arxi-store/src/sqlite/connection.rs L12-L21

SqliteConnection::execute utilitza sync_channel limitat + canals oneshot per connectar codi asíncron amb operacions síncrones de rusqlite. L’admissió a la cua és explícita: la saturació de la cua falla tancada amb StoreError::ConcurrencyConflict en lloc de permetre un creixement il·limitat de treball en memòria. F:crates/arxi-store/src/sqlite/connection.rs L42-L136 F:crates/arxi-store/src/sqlite/connection.rs L167-L222

SqliteStore exposa addicionalment helpers de metadades tipades sobre store_meta (get_meta, set_meta, set_meta_batch) per a l’estat de temps d’execució determinista, com ara els marcadors d’idempotència de rotació de clau de signatura. F:crates/arxi-store/src/sqlite/mod.rs

Esquema SQLite i Indexació

La inicialització permet:

mode WAL,
claus foranes,
taula de metadades de l’esquema,
segments, envoltants, fitxers adjunts i taules de connexió normalitzades,
índexs per a patrons de consulta d’envolupament/segment deterministes.

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

Aplicació de la Continuïtat de la Cadena

Ambdós backends imposen la validació de la cadena en temps d’append mitjançant la recomputació de l’encapçalament de cadena esperat i la comparació en temps constant.

Validació d’apèndix en memòria: F:crates/arxi-store/src/memory.rs L140-L158

La validació d’apèndix de SQLite és limitada a la transacció:

verificar que el segment existeix i està obert,
recalcular el hash esperat de la cadena,
rebutjar desajustaments,
inserir files d’envelopes + files d’adjunt d’envelopes,
actualitzar la metadada del segment de manera atòmica.

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

Semàntica de Consulta i Paginació

Les consultes d’envelopes suporten filtratge de múltiples camps, així com continuació de cursor i límit. L’ordre de consulta de SQLite és ORDER BY segment_id, sequence; les consultes d’envelopes de segment s’ordenen per sequence ASC.

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

La llista de segments admet filtres d’estat/temps/id i ordena per created_at ASC. F:crates/arxi-store/src/sqlite/segment_ops.rs L148-L245

Corrupció i Gestió d’Errors

StoreError diferencia explícitament les ruptures d’integritat, els casos no trobats, els conflictes de concurrència, les fallades del backend i la detecció de corrupció. F:crates/arxi-store/src/error.rs L36-L103

El processament de segments d’SQLite tracta els valors de DB no vàlids com a corrupció (UUID no vàlid, estat desconegut, algorisme de hash desconegut, timestamps no vàlids). F:crates/arxi-store/src/sqlite/segment_ops.rs L336-L416

Les proves del sistema ara validen el comportament de fallada tancada quan les files de SQLite persistents són manipulades amb dades de UUID/genesis de segment no vàlides entre les operacions de CLI. F:system-tests/tests/suites/persistence.rs L375-L468

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Contractes d’emmagatzematge	`crates/arxi-store/src/traits.rs`	Invariants del trait d’emmagatzematge canònic.
Tipus de segments	`crates/arxi-store/src/types.rs`	Metadades de segment i formes de filtre.
Backend en memòria	`crates/arxi-store/src/memory.rs`	Implementació basada en mapes determinista.
Façana SQLite	`crates/arxi-store/src/sqlite/mod.rs`	Construcció de l’emmagatzematge i composició del backend.
Helpers de metadades SQLite	`crates/arxi-store/src/sqlite/mod.rs`	Helpers de lectura/escriptura `store_meta` per a la persistència de l’estat en temps d’execució.
Pont SQLite	`crates/arxi-store/src/sqlite/connection.rs`	Pont async dedicat a fils.
Esquema SQLite	`crates/arxi-store/src/sqlite/schema.rs`	DDL, índexs, versionat d’esquema.
Operacions SQL d’envolupament	`crates/arxi-store/src/sqlite/envelope_ops.rs`	Lògica de consulta de filtre i append transaccionals.
Operacions SQL de segment	`crates/arxi-store/src/sqlite/segment_ops.rs`	Cicle de vida del segment i decodificació de metadades.
Operacions SQL d’adjunt	`crates/arxi-store/src/sqlite/attachment_ops.rs`	Semàntica de put/get/exists adreçada al contingut.
Taxonomia d’errors	`crates/arxi-store/src/error.rs`	Model de fallada d’emmagatzematge tipificat.