Arquitectura de Almacenamiento Arxi

Audience: Engineers changing persistence logic, query semantics, schema, Audiencia: Ingenieros que cambian la lógica de persistencia, la semántica de consultas, el esquema o los backends de almacenamiento.

Tabla de Contenidos

Resumen Ejecutivo
Contratos de Rasgos de Almacenamiento
Backend en memoria
Backend de SQLite
Esquema de SQLite e Indexación
Cumplimiento de la Continuidad de la Cadena
Semántica de Consulta y Paginación
Corrupción y Manejo de Errores
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

arxi-store proporciona la abstracción de persistencia y dos backends concretos:

InMemoryStore para pruebas deterministas y ejecución local,
SqliteStore para operación duradera con WAL y verificaciones transaccionales.

Ambos implementan contratos de rasgos compartidos para operaciones de sobre, adjunto y segmento. F:crates/arxi-store/src/lib.rs L11-L37 F:crates/arxi-store/src/lib.rs L49-L71

Contratos de Rasgos de Almacén

El contrato de almacenamiento se expresa como tres rasgos asíncronos:

EnvelopeStore: agregar/obtener/consultar/cabeza de cadena/segmentar sobres,
AttachmentStore: poner/obtener/existe para blobs dirigidos por contenido,
SegmentStore: crear/sellar/listar/obtener metadatos y génesis.

Los invariantes centrales incluyen un comportamiento de solo anexar, verificaciones de continuidad de la cadena y la inmutabilidad de segmentos sellados. La creación de segmentos es de cierre seguro: los almacenes rechazan un nuevo segmento cuando ya existe otro segmento abierto o cuando el ID del segmento ya existe. 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 memoria

InMemoryStore utiliza mapas y vectores protegidos por bloqueo, preservando las verificaciones de invariante pero sin garantías de consistencia ante fallos. F:crates/arxi-store/src/memory.rs L12-L16

Destacados del comportamiento:

valida el estado del segmento y la continuidad de la cadena al agregar,
mantiene las actualizaciones de los IDs de sobre primero/último y de la cadena principal,
aplica reglas de creación de segmento único abierto y sin ID de segmento duplicado,
admite la enumeración de segmentos deterministas por created_at,
impone un orden de consulta de sobreenvoltura determinista por segment_id y luego por secuencia.

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

SQLite Backend

SqliteStore dirige todas las operaciones de la base de datos a través de un hilo de conexión dedicado (SqliteConnection) para preservar de manera segura la semántica de un solo escritor entre los llamadores asíncronos. F:crates/arxi-store/src/sqlite/mod.rs L12-L22 F:crates/arxi-store/src/sqlite/connection.rs L12-L21

SqliteConnection::execute utiliza sync_channel acotados + canales oneshot para conectar código asíncrono con operaciones síncronas de rusqlite. La admisión en la cola es explícita: la saturación de la cola falla cerrada con StoreError::ConcurrencyConflict en lugar de permitir un crecimiento ilimitado del trabajo en memoria. F:crates/arxi-store/src/sqlite/connection.rs L42-L136 F:crates/arxi-store/src/sqlite/connection.rs L167-L222

SqliteStore expone además ayudantes de metadatos tipados sobre store_meta (get_meta, set_meta, set_meta_batch) para el estado de tiempo de ejecución determinista, como marcadores de idempotencia para la rotación de claves de firmante. F:crates/arxi-store/src/sqlite/mod.rs

Esquema de SQLite e Indexación

La inicialización habilita:

modo WAL,
claves foráneas,
tabla de metadatos del esquema,
segmentos normalizados, sobres, adjuntos y tablas de unión,
índices para patrones de consulta de sobre/envelope y segmento determinísticos.

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

Cumplimiento de la Continuidad de la Cadena

Ambos backends imponen la validación de cadenas en el tiempo de anexado utilizando la recomputación de la cabeza de cadena esperada y la comparación en tiempo constante.

Validación de anexos en memoria: F:crates/arxi-store/src/memory.rs L140-L158

La validación de anexos de SQLite está limitada al ámbito de la transacción:

verificar que el segmento exista y esté abierto,
recalcular el hash de cadena esperado,
rechazar desajuste,
insertar filas de sobre + adjunto de sobre,
actualizar los metadatos del segmento de forma atómica.

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

Semántica de Consulta y Paginación

Las consultas de sobreenvoltura admiten filtrado de múltiples campos, además de continuación de cursor y límite. El orden de consulta de SQLite es ORDER BY segment_id, sequence; las consultas de segmento-sobreenvoltura se ordenan por 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 lista de segmentos admite filtros de estado/tiempo/id y ordena por created_at ASC. F:crates/arxi-store/src/sqlite/segment_ops.rs L148-L245

Corrupción y Manejo de Errores

StoreError diferencia explícitamente las interrupciones de integridad, los casos no encontrados, los conflictos de concurrencia, las fallas del backend y la detección de corrupción. F:crates/arxi-store/src/error.rs L36-L103

El análisis de segmentos de SQLite trata los valores de base de datos inválidos como corrupción (UUID inválido, estado desconocido, algoritmo de hash desconocido, marcas de tiempo inválidas). F:crates/arxi-store/src/sqlite/segment_ops.rs L336-L416

Las pruebas del sistema ahora validan el comportamiento de cierre en caso de fallo cuando las filas de SQLite persistidas son manipuladas con datos de UUID/genesis de segmento inválidos entre operaciones de CLI. F:system-tests/tests/suites/persistence.rs L375-L468

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Contratos de almacenamiento	`crates/arxi-store/src/traits.rs`	Invariantes de rasgos de almacenamiento canónicos.
Tipos de segmento	`crates/arxi-store/src/types.rs`	Metadatos de segmento y formas de filtro.
Backend en memoria	`crates/arxi-store/src/memory.rs`	Implementación determinista basada en mapas.
Fachada de SQLite	`crates/arxi-store/src/sqlite/mod.rs`	Construcción de almacenamiento y composición de backend.
Ayudantes de metadatos de SQLite	`crates/arxi-store/src/sqlite/mod.rs`	Ayudantes de lectura/escritura `store_meta` para la persistencia del estado en tiempo de ejecución.
Puente de SQLite	`crates/arxi-store/src/sqlite/connection.rs`	Puente asíncrono dedicado a hilos.
Esquema de SQLite	`crates/arxi-store/src/sqlite/schema.rs`	DDL, índices, versionado de esquema.
Operaciones SQL de sobreenvoltura	`crates/arxi-store/src/sqlite/envelope_ops.rs`	Lógica de consulta de apéndice y filtro transaccional.
Operaciones SQL de segmento	`crates/arxi-store/src/sqlite/segment_ops.rs`	Ciclo de vida del segmento y decodificación de metadatos.
Operaciones SQL de adjunto	`crates/arxi-store/src/sqlite/attachment_ops.rs`	Semántica de put/get/exists dirigida por contenido.
Taxonomía de errores	`crates/arxi-store/src/error.rs`	Modelo de fallo de almacenamiento tipado.