Arxi Arquitectura del Sistema

Audience: Engineers working across Arxi crates or integrating Arxi with Audiència: Enginyers que treballen amb caixes Arxi o integrant Arxi amb sistemes de control com Decision Gate.

Taula de continguts

Visió Executiva
Arquitectura en Capes
Flux de dades de principi a fi
Límits de confiança i postura de seguretat
Model de Determinisme
Abast d’implementació actual
File per Fitxer Referència Creuada

Executive Overview

Arxi és un pla de dades per a la gravació d’evidències deterministes. Captura esdeveniments no segellats a les fronteres dels adaptadors, els segella en sobres encadenats per hash, els persisteix en històries de segments només d’append, i exporta paquets portàtils per a la verificació fora de línia.

El sistema està organitzat com un espai de treball de Rust amb límits estrictes de crate: contractes bàsics, model d’envolupament, orquestració de gravadors, backend d’emmagatzematge, semàntica de configuració de sidecar canònica, operacions CLI i un servei HTTP de sidecar en temps d’execució. F:Cargo.toml L9-L26

Arquitectura en capes

Core contracts (arxi-core)
- Identity newtypes, hash/signature abstractions, filters, schema versioning, and boundary error algebras. Identitats de nous tipus, abstraccions de hash/signatura, filtres, versionat d’esquema, i àlgebra d’errors 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. Tipus d’envelopes/segments/paquets, funcions d’encoding canòniques, contractes d’adaptador i proveïdor, i àlgebra dels resultats de verificació. 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 primer nivell que implementa el mapeig de transcripcions MCP/runpack de Decision Gate, política de redacció/límits i comprovacions d’integritat del 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 i implementació del proveïdor. F:crates/arxi-recorder/src/lib.rs L34-L56
Persistence (arxi-store)
- Store traits with SQLite and in-memory implementations. Emmagatzemar característiques amb implementacions SQLite i en memòria. 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. Model de configuració de sidecar canònic, validació en temps d’execució fallida, i ajudants de projecció de configuració determinista consumits per 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 Grups de comandes CLI per al cicle de vida del segment, gravació, consulta, paquet, validació de configuració, diagnòstics, ingestió conscient d’adjunts i ingestió de fixtures de Decision Gate, amb gestors dividits en mòduls de comanda i mòduls d’ajuda de suport. 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 amb middleware d’autenticació/límits/idempotència i integració de gravació/emmagatzematge sobre oients Unix/TCP, incloent probes de viabilitat/inici/preparació explícits i modes de preparació conscients de l’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ó/comprovació d’artefactes deterministes (Docs/generated/arxi/**) i autoritat de hash del manifest (index.json). F:crates/arxi-contract/src/lib.rs

Flux de dades de principi a fi

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

Punts d’entrada clau del flux:

Ingest path: RecorderEngine::record_envelope Ruta d’ingesta: RecorderEngine::record_envelope F:crates/arxi-recorder/src/engine.rs L207-L214
Segment lifecycle: open_segment, seal_segment Cicle de vida del segment: open_segment, seal_segment F:crates/arxi-recorder/src/engine.rs L280-L343
Bundle export path: BundleBuilder::build Ruta d’exportació del paquet: BundleBuilder::build F:crates/arxi-recorder/src/bundle_builder.rs L129-L172
Offline verification path: Verifier::verify Camí de verificació offline: Verifier::verify F:crates/arxi-recorder/src/verifier.rs L95-L136

Límits de confiança i postura de seguretat

Adapter inputs are treated as untrusted and validated fail-closed before recorder append. Les entrades de l’adaptador es tracten com a no confiables i es validen per fallar tancades abans de l’append del gravador. 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. L’append de l’emmagatzematge imposa la continuïtat de la cadena i rebutja les escriptures a segments segellats. 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 distribució de SQLite ara utilitza l’admissió de cua limitada i el rebuig de saturació determinista en lloc del buffer d’operacions il·limitat. 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

Model de Determinisme

El determinisme s’aconsegueix combinant:

codificació JCS canònica per a dades hashables,
estructures d’ordenació deterministes (BTreeMap, vectors ordenats),
lògica de hash estable i de selector,
verificació offline reproduïble.

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

Abast de la Implementació Actual

Implementat ara:

Cicle de gravació local complet i verificació de paquets.
SQLite/emmagatzematge en memòria.
Operacions impulsades per CLI i sortida localitzada.
CLI attachment-aware recording (record-with-attachments) with bounded file Gravació conscient d’adjuncions de CLI (record-with-attachments) amb fitxers limitats i entrades d’adjuncions en línia.
CLI Decision Gate fixture ingest command path wired to production adapter Ruta de comandament d’ingestió del dispositiu de Decision Gate del CLI connectada a la implementació de l’adaptador de producció.
System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest proves d’integració.
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 CLI ingest-fixture èxit/fallida estricta rutes.
Production Decision Gate adapter crate (crates/arxi-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript controls de redacció/límits.
OpenClaw integration harness mapping policy with deterministic sensitive-field Política de mapeig de l’integració d’OpenClaw amb redacció de camps sensibles determinista i gestió de càrregues limitades per a proves de connexió basades en fixtures.
Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch Sistema d’integració de Decision Gate amb proves de sistema connectades a la caixa d’adaptador de producció, cobrint comportaments de fallada tancada per discrepàncies en les pistes signades/no signades, el hash arrel i la integritat del manifest, així com la reproducció/hash determinista i l’estabilitat.
Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/open/record/query flux.
Sidecar readiness semantics now support fail-closed dependency modes: La semàntica de preparació del Sidecar ara admet modes de dependència que fallen tancats: preparació només d’emmagatzematge i preparació d’emmagatzematge + control empresarial.

Gaps actuals post-nucli en el comportament a nivell de sistema:

L’expansió de la prova del sistema de rendiment/estrès P2 continua oberta.
Sidecar release-grade perf/soak promotion remains opt-in via La promoció de rendiment/absorció de la versió Sidecar continua sent optativa a través de ARXI_SIDECAR_PERF_GATE=1 i encara requereix ajustaments del perfil CI.

Elements de reforç a nivell de sistema recentment tancats:

Provider listing/fetch now uses stable bundle IDs and fetch-by-ID segment selectors. La llista/recuperació del proveïdor ara utilitza identificadors de paquet estables i selectors de segment de recuperació per 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. L’operació de dispatch de SQLite ara aplica pressió de cua limitada amb un comportament de fallada de saturació 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ó de contractes ara superposa esquemes inferits amb restriccions autoritatives en temps d’execució i tanca en cas de falta de punts de referència de restricció. 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 ara executa comprovacions de signatura de trust-root amb avaluació de política (salta l’advertència només quan no s’ofereix cap trust root). 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

File per Fitxer Referència Creuada

Àrea	Fitxer	Notes
Límits de l’espai de treball	`Cargo.toml`	Membresia del crate i postura de lint.
Contractes bàsics	`crates/arxi-core/src/lib.rs`	Primitives i traits de domini compartit.
Model d’envolupant	`crates/arxi-envelope/src/lib.rs`	Model de dades d’evidència i contractes.
Temps d’execució del gravador	`crates/arxi-recorder/src/engine.rs`	Ingesta, progressió de cadena, cicle de vida del segment.
Paquet + verificador	`crates/arxi-recorder/src/bundle_builder.rs`	Resolució de selectors i materialització de paquets.
Verificació de paquets	`crates/arxi-recorder/src/verifier.rs`	Verificació offline en 7 fases.
Traits d’emmagatzematge	`crates/arxi-store/src/traits.rs`	Invariants del contracte de persistència.
Límits de cua SQLite	`crates/arxi-store/src/sqlite/connection.rs`	Dispatch limitat d’asíncron a sincró i comportament de saturació tancat per fallada.
Superfície CLI	`crates/arxi-cli/src/main.rs`, `crates/arxi-cli/src/commands.rs`, `crates/arxi-cli/src/support.rs`	Arquitectura de comandes operatives dividida entre dispatch, gestors de comandes i helpers d’execució/utilitat.
Servei de sidecar	`crates/arxi-sidecar/src/lib.rs`, `crates/arxi-sidecar/src/server.rs`	Temps d’execució HTTP, pila de middleware i cicle de vida del transport.
Configuració/seguretat 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ó de configuració tancada per fallada i autoritat de projecció més controls d’autenticació/límits del sidecar i comportament d’idempotència persistent.
Embalatge de contenidors del sidecar	`docker/sidecar/Dockerfile`, `docker/sidecar/docker-compose.yml`, `docker/sidecar/config/sidecar.toml`	Perfil de construcció/execució de contenidors de primera part alineat amb invariants de validació/seguretat del sidecar.
Generador de contractes	`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`	Autoritat d’artefactes generats determinísticament + verificacions de deriva.
Proves de sistema	`system-tests/README.md`	Contracte de validació de punta a punta.
Adaptador de Decision Gate	`crates/arxi-decision-gate-adapter/src/adapter.rs`	Implementació de mapeig/redacció/política d’integritat per a la ingesta de Decision Gate.
Proves d’integració d’OpenClaw	`system-tests/tests/suites/integration_openclaw.rs`	Verificació d’ingesta d’adaptador basada en fixtures per a acoblament de fluxos de treball externs.
Arquitectura d’integració d’OpenClaw	Docs/architecture/arxi_openclaw_integration_architecture.md	Contracte de mapeig versionat i política de redacció/càrrega limitada.
Proves d’integració de Decision Gate	`system-tests/tests/suites/integration_decision_gate.rs`	Verificació d’ingesta de flux de MCP basada en fixtures per a acoblament de pla de control.
Arquitectura d’integració de Decision Gate	Docs/architecture/arxi_decision_gate_integration_architecture.md	Mapeig de flux de MCP versionat, política d’integritat de runpack i contracte de redacció/límits de transcripció.