Arquitectura del Sistema Arxi

Audience: Engineers working across Arxi crates or integrating Arxi with Audiencia: Ingenieros que trabajan con crates de Arxi o integrando Arxi con sistemas de plano de control como Decision Gate.

Tabla de Contenidos

Resumen Ejecutivo
Arquitectura en Capas
Flujo de Datos de Extremo a Extremo
Límites de Confianza y Postura de Seguridad
Modelo de Determinismo
Alcance de Implementación Actual
Referencia Cruzada Archivo por Archivo

Resumen Ejecutivo

Arxi es un plano de datos para el registro de evidencia determinista. Captura eventos no sellados en los límites de los adaptadores, los sella en sobres encadenados por hash, los persiste en historiales de segmentos de solo anexado y exporta paquetes portátiles para verificación fuera de línea.

El sistema está organizado como un espacio de trabajo de Rust con límites de crate estrictos: contratos centrales, modelo de sobre, orquestación de grabadores, backends de almacenamiento, semánticas de configuración de sidecar canónicas, operaciones de CLI y un tiempo de ejecución de servicio HTTP de sidecar. F:Cargo.toml L9-L26

Arquitectura en Capas

Core contracts (arxi-core)
- Identity newtypes, hash/signature abstractions, filters, schema versioning, and boundary error algebras. Identidades de nuevos tipos, abstracciones de hash/firma, filtros, versionado de esquemas y álgebras de errores de frontera. F:crates/arxi-core/src/lib.rs L53-L109
Evidence model (arxi-envelope)
- Envelope/segment/bundle types, canonical encoding functions, adapter and provider contracts, and verification result algebra. Tipos de sobre/segmento/lote, funciones de codificación canónica, contratos de adaptador y proveedor, y álgebra de resultados de verificación. F:crates/arxi-envelope/src/lib.rs L53-L111
Integration adapters (arxi-decision-gate-adapter)
- First-party deterministic adapter implementing Decision Gate MCP/runpack transcript mapping, redaction/bounds policy, and runpack-integrity checks. Adaptador determinista de primera parte que implementa el mapeo de transcripciones de Decision Gate MCP/runpack, política de redacción/límites y verificaciones de integridad de runpack. F:crates/arxi-decision-gate-adapter/src/lib.rs L1-L40
Recording runtime (arxi-recorder)
- RecorderEngine, BundleBuilder, Verifier, local adapter, and provider implementation. RecorderEngine, BundleBuilder, Verifier, adaptador local e implementación de proveedor. F:crates/arxi-recorder/src/lib.rs L34-L56
Persistence (arxi-store)
- Store traits with SQLite and in-memory implementations. Almacenar rasgos con implementaciones de SQLite y en memoria. F:crates/arxi-store/src/lib.rs L49-L71
Sidecar config authority (arxi-sidecar-config)
- Canonical sidecar config model, fail-closed runtime validation, and deterministic config projection helpers consumed by arxi-contract. Modelo de configuración de sidecar canónico, validación de tiempo de ejecución que falla en cerrado y ayudantes de proyección de configuración determinista consumidos por arxi-contract. F:crates/arxi-sidecar-config/src/lib.rs
Operational surface (arxi-cli)
- CLI command groups for segment lifecycle, recording, query, bundle, config validation, diagnostics, attachment-aware ingest, and Decision Gate fixture ingest, with handlers split into command and support helper modules. F:crates/arxi-cli/src/main.rs L137-L272 F:crates/arxi-cli/src/commands.rs L19-L29 Grupos de comandos CLI para el ciclo de vida de segmentos, grabación, consulta, paquete, validación de configuración, diagnóstico, ingestión consciente de adjuntos y ingestión de accesorios de Decision Gate, con controladores divididos en módulos de comando y soporte auxiliar. F:crates/arxi-cli/src/main.rs L137-L272 F:crates/arxi-cli/src/commands.rs L19-L29 F:crates/arxi-cli/src/support.rs L19-L23
Network service surface (arxi-sidecar)
- Sidecar HTTP/JSON runtime with auth/bounds/idempotency middleware and recorder/store integration over Unix/TCP listeners, including explicit liveness/startup/readiness probes and enterprise-aware readiness modes. F:crates/arxi-sidecar/src/lib.rs L1-L41 Runtime HTTP/JSON de Sidecar con middleware de autenticación/límites/idempotencia e integración de grabadora/almacenamiento sobre oyentes Unix/TCP, incluyendo sondas explícitas de disponibilidad/inicio/listo y modos de disponibilidad conscientes de la empresa. F:crates/arxi-sidecar/src/lib.rs L1-L41 F:crates/arxi-sidecar/src/server.rs L42-L247
Projection contract generation (arxi-contract)
- Deterministic artifact generation/check (Docs/generated/arxi/**) and manifest hash authority (index.json). Generación/verificación de artefactos deterministas (Docs/generated/arxi/**) y autoridad de hash de manifiesto (index.json). F:crates/arxi-contract/src/lib.rs

Flujo de Datos de Extremo a Extremo

Adapter / CLI input
    -> UnsealedEnvelope
    -> RecorderEngine computes content_hash + chain_hash + sequence
    -> EnvelopeStore append (chain continuity enforced)
    -> Segment lifecycle (open/seal, predecessor linkage)
    -> BundleBuilder resolves selector + attachment closure + manifest
    -> Verifier runs 7 phases offline
    -> EvidenceProvider serves bundles/envelope queries to control-plane bridge

Puntos de entrada clave del flujo:

Ingest path: RecorderEngine::record_envelope Ruta de ingestión: RecorderEngine::record_envelope F:crates/arxi-recorder/src/engine.rs L207-L214
Segment lifecycle: open_segment, seal_segment Ciclo de vida del segmento: open_segment, seal_segment F:crates/arxi-recorder/src/engine.rs L280-L343
Bundle export path: BundleBuilder::build Ruta de exportación del paquete: BundleBuilder::build F:crates/arxi-recorder/src/bundle_builder.rs L129-L172
Offline verification path: Verifier::verify Ruta de verificación fuera de línea: Verifier::verify F:crates/arxi-recorder/src/verifier.rs L95-L136

Límites de Confianza y Postura de Seguridad

Adapter inputs are treated as untrusted and validated fail-closed before recorder append. Las entradas del adaptador se tratan como no confiables y se validan para fallar en cerrado antes de la adición del grabador. F:crates/arxi-recorder/src/validation.rs L46-L83
Core identity constructors fail closed on blank/control-character strings, and KeyId enforces canonical lowercase SHA-256 hex shape. String-backed identity types now also enforce explicit max-length policies and constructor-validated serde deserialization. F:crates/arxi-core/src/identity.rs L31-L55 F:crates/arxi-core/src/identity.rs L37-L47 F:crates/arxi-core/src/identity.rs L516-L647
Envelope-layer attachment and segment constructors reject empty/blank/control text inputs for content_type and recorder_id, enforce max-length bounds, and validate serde deserialize boundaries through constructors. F:crates/arxi-envelope/src/attachment.rs L35-L44 F:crates/arxi-envelope/src/attachment.rs L79-L96 F:crates/arxi-envelope/src/segment.rs L42-L56 F:crates/arxi-envelope/src/segment.rs L91-L118
Store append enforces chain continuity and rejects writes to sealed segments. Store append impone la continuidad de la cadena y rechaza escrituras en segmentos sellados. F:crates/arxi-store/src/traits.rs L47-L66
Verifier and provider library boundaries enforce bounded-work fail-closed policies to protect embedding wrappers from unbounded in-memory workloads. F:crates/arxi-recorder/src/verifier.rs L73-L246 F:crates/arxi-recorder/src/evidence_provider.rs L52-L300
SQLite dispatch now uses bounded queue admission and deterministic saturation rejection rather than unbounded operation buffering. La gestión de SQLite ahora utiliza la admisión de cola limitada y el rechazo de saturación determinista en lugar de un almacenamiento en búfer de operaciones ilimitadas. F:crates/arxi-store/src/sqlite/connection.rs L42-L136
Sidecar HTTP boundary enforces request identity, optional bearer-token auth with constant-time compare, protocol/header/body bounds, bounded queue and active concurrency gates, timeout fail-closed behavior, and persistent idempotency replay/conflict controls. Probe routes (/health, /startup, /ready) are explicitly exempt from those request gates so orchestration liveness/startup/readiness signals remain observable under stress. F:crates/arxi-sidecar/src/middleware/request_id.rs L15-L30 F:crates/arxi-sidecar/src/middleware/auth.rs L21-L84 F:crates/arxi-sidecar/src/middleware/bounds.rs L21-L172 F:crates/arxi-sidecar/src/idempotency.rs L20-L316
Sidecar container packaging is first-party in-repo and keeps the same fail-closed config + token-hardening model under distroless nonroot runtime and explicit UID/GID bind-mount mapping. F:docker/sidecar/Dockerfile F:docker/sidecar/docker-compose.yml F:docker/sidecar/config/sidecar.toml
Hash equality uses constant-time comparison in core, verifier, and stores. F:crates/arxi-core/src/hash.rs L102-L174 F:crates/arxi-recorder/src/verifier.rs L29-L52 F:crates/arxi-store/src/sqlite/envelope_ops.rs L62-L79

Modelo de Determinismo

El determinismo se logra combinando:

codificación JCS canónica para datos hashables,
estructuras de ordenamiento deterministas (BTreeMap, vectores ordenados),
lógica de hash estable y de selector,
verificación reproducible sin conexión.

F:crates/arxi-envelope/src/encoding.rs L13-L31 F:crates/arxi-recorder/src/bundle_builder.rs L27-L30 F:crates/arxi-recorder/src/bundle_builder.rs L466-L477

Alcance de Implementación Actual

Implementado ahora:

Ciclo de vida completo de grabación local y verificación de paquetes.
Backend de almacenamiento SQLite/en memoria.
Operaciones impulsadas por CLI y salida localizada.
CLI attachment-aware recording (record-with-attachments) with bounded file Grabación consciente de archivos adjuntos en CLI (record-with-attachments) con entradas de archivo limitado y adjuntos en línea.
CLI Decision Gate fixture ingest command path wired to production adapter Ruta del comando de ingestión del accesorio de la puerta de decisión de CLI conectada a la implementación del adaptador de producción.
System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest pruebas de integración.
CLI expansion system-tests for recorder-id shape validation parity, attachment-recording fail-closed boundaries, auto-seal duration/combined lifecycle behavior, query JSON pagination/limit guardrails, and Decision Gate Rutas de éxito/fallo estricto de ingest-fixture en la CLI.
Production Decision Gate adapter crate (crates/arxi-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript controles de límites de redacción.
OpenClaw integration harness mapping policy with deterministic sensitive-field Política de mapeo del arnés de integración de OpenClaw con redacción determinista de campos sensibles y manejo de carga útil acotada para pruebas de acoplamiento impulsadas por fixture.
Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch Sistema de pruebas de integración de Decision Gate conectado a la caja del adaptador de producción, cubriendo comportamientos de fallo cerrado por desajuste de carriles firmados/no firmados, raíz-hash y manifiesto-integridad.
Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/open/record/query flujo.
Sidecar readiness semantics now support fail-closed dependency modes: La semántica de disponibilidad del sidecar ahora admite modos de dependencia que fallan en cerrado: disponibilidad solo de almacenamiento y disponibilidad de almacenamiento + control empresarial.

Gaps actuales post-núcleo en el comportamiento a nivel de sistema:

La expansión de la prueba del sistema de rendimiento/estrés P2 permanece abierta.
Sidecar release-grade perf/soak promotion remains opt-in via La promoción de rendimiento/soak de la versión de Sidecar sigue siendo optativa a través de ARXI_SIDECAR_PERF_GATE=1 y aún requiere ajuste del perfil de CI.

Elementos de endurecimiento a nivel de sistema recientemente cerrados:

Provider listing/fetch now uses stable bundle IDs and fetch-by-ID segment selectors. La lista de proveedores/recuperación ahora utiliza identificadores de paquete estables y selectores de segmento de recuperación por ID. F:crates/arxi-recorder/src/evidence_provider.rs L125-L229
Recorder verifier/provider now enforce explicit bounded-work policy and reject oversized workloads fail-closed at library boundaries. F:crates/arxi-recorder/src/verifier.rs L73-L246 F:crates/arxi-recorder/src/evidence_provider.rs L52-L300
SQLite operation dispatch now applies bounded queue backpressure with deterministic saturation failure behavior. La operación de despacho de SQLite ahora aplica presión de retroceso de cola limitada con un comportamiento de fallo de saturación determinista. F:crates/arxi-store/src/sqlite/connection.rs L42-L203
Contract generation now overlays inferred schemas with authoritative runtime constraints and fail-closes on missing constraint pointer targets. La generación de contratos ahora superpone esquemas inferidos con restricciones de tiempo de ejecución autorizadas y cierra en caso de fallos por objetivos de puntero de restricción faltantes. F:crates/arxi-contract/src/lib.rs L565-L742
Sidecar contract-generation/projection integration is now implemented with generated API artifacts (openapi/errors/enums/examples/compat) and fail-closed compatibility gates in CI orchestration. F:crates/arxi-contract/src/lib.rs F:scripts/ci/sidecar_contract_gates.py F:scripts/ci/generate_all.sh
Verifier phase 6 now executes trust-root signature checks with policy evaluation (skip warning only when no trust root is provided). La fase 6 del verificador ahora ejecuta comprobaciones de firma de raíz de confianza con evaluación de políticas (omitir advertencia solo cuando no se proporciona ninguna raíz de confianza). F:crates/arxi-recorder/src/verifier.rs L509-L651
Startup read-back verification now executes from RecorderEngine::new when startup_verification_depth > 0. F:crates/arxi-recorder/src/engine.rs L154-L197 F:crates/arxi-recorder/src/engine.rs L380-L543

Referencia Cruzada Archivo por Archivo

Área	Archivo	Notas
Límites del espacio de trabajo	`Cargo.toml`	Membresía de crate y postura de lint.
Contratos centrales	`crates/arxi-core/src/lib.rs`	Primitivas y rasgos de dominio compartidos.
Modelo de sobre	`crates/arxi-envelope/src/lib.rs`	Modelo de datos de evidencia y contratos.
Tiempo de ejecución del grabador	`crates/arxi-recorder/src/engine.rs`	Ingesta, progresión de cadena, ciclo de vida de segmento.
Paquete + verificador	`crates/arxi-recorder/src/bundle_builder.rs`	Resolución de selectores y materialización de paquetes.
Verificación de paquetes	`crates/arxi-recorder/src/verifier.rs`	Verificación fuera de línea en 7 fases.
Rasgos de almacenamiento	`crates/arxi-store/src/traits.rs`	Invariantes del contrato de persistencia.
Límite de cola de SQLite	`crates/arxi-store/src/sqlite/connection.rs`	Comportamiento de despacho asíncrono a síncrono limitado y fallo cerrado por saturación.
Superficie de CLI	`crates/arxi-cli/src/main.rs`, `crates/arxi-cli/src/commands.rs`, `crates/arxi-cli/src/support.rs`	Arquitectura de comandos operativos dividida en despacho, manejadores de comandos y ayudantes de tiempo de ejecución/utilidad.
Servicio de sidecar	`crates/arxi-sidecar/src/lib.rs`, `crates/arxi-sidecar/src/server.rs`	Tiempo de ejecución HTTP, pila de middleware y ciclo de vida de transporte.
Configuración/seguridad del sidecar	`crates/arxi-sidecar-config/src/config.rs`, `crates/arxi-sidecar-config/src/validation.rs`, `crates/arxi-sidecar/src/middleware/auth.rs`, `crates/arxi-sidecar/src/middleware/bounds.rs`, `crates/arxi-sidecar/src/idempotency.rs`	Validación de configuración cerrada por fallo y autoridad de proyección más controles de autenticación/límites del sidecar y comportamiento de idempotencia persistente.
Empaquetado de contenedores de sidecar	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`	Perfil de construcción/tiempo de ejecución de contenedor de primera parte alineado con invariantes de validación/seguridad del sidecar.
Generador de contratos	`crates/arxi-contract/src/lib.rs`, `crates/arxi-contract/src/sidecar_api.rs`, `crates/arxi-contract/src/sidecar_api/openapi.rs`, `crates/arxi-contract/src/sidecar_api/artifacts.rs`, `crates/arxi-contract/src/sidecar_api/specs/mod.rs`	Autoridad de artefactos generados determinísticos + verificaciones de deriva.
Pruebas del sistema	`system-tests/README.md`	Contrato de validación de extremo a extremo.
Adaptador de puerta de decisión	`crates/arxi-decision-gate-adapter/src/adapter.rs`	Implementación de políticas de mapeo/redacción/integridad para la ingesta de la puerta de decisión.
Pruebas de integración de OpenClaw	`system-tests/tests/suites/integration_openclaw.rs`	Verificación de ingesta de adaptador impulsada por fixture para acoplamiento de flujo de trabajo externo.
Arquitectura de integración de OpenClaw	Docs/architecture/arxi_openclaw_integration_architecture.md	Contrato de mapeo y redacción/política de carga útil limitada versionada.
Pruebas de integración de la puerta de decisión	`system-tests/tests/suites/integration_decision_gate.rs`	Verificación de ingesta de flujo de ejecución MCP impulsada por fixture para acoplamiento de plano de control.
Arquitectura de integración de la puerta de decisión	Docs/architecture/arxi_decision_gate_integration_architecture.md	Contrato de mapeo de flujo MCP versionado, política de integridad de ejecución y redacción/límites de transcripción.