Arxi Decision Gate Asset Core
Docs
Arxi Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Arxi System Architecture

Audience: Engineers working across Arxi crates or integrating Arxi with control-plane systems such as Decision Gate.

Table of Contents

  1. Executive Overview
  2. Layered Architecture
  3. End-to-End Data Flow
  4. Trust Boundaries and Security Posture
  5. Determinism Model
  6. Current Implementation Scope
  7. File-by-File Cross Reference

Executive Overview

Arxi is a data plane for deterministic evidence recording. It captures unsealed events at adapter boundaries, seals them into hash-chained envelopes, persists them in append-only segment histories, and exports portable bundles for offline verification.

The system is organized as a Rust workspace with strict crate boundaries: core contracts, envelope model, recorder orchestration, storage backends, canonical sidecar config semantics, CLI operations, and a sidecar HTTP service runtime. F:Cargo.toml L9-L26

Layered Architecture

  1. Core contracts (arxi-core)
  2. Evidence model (arxi-envelope)
  3. Integration adapters (arxi-decision-gate-adapter)
  4. Recording runtime (arxi-recorder)
  5. Persistence (arxi-store)
  6. Sidecar config authority (arxi-sidecar-config)
  7. Operational surface (arxi-cli)
  8. Network service surface (arxi-sidecar)
  9. Projection contract generation (arxi-contract)

End-to-End Data Flow

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

Key flow entry points:

Trust Boundaries and Security Posture

Determinism Model

Determinism is achieved by combining:

  • canonical JCS encoding for hashable data,
  • deterministic ordering structures (BTreeMap, sorted vectors),
  • stable hash and selector logic,
  • replayable offline verification.

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

Current Implementation Scope

Implemented now:

  • Full local recording lifecycle and bundle verification.
  • SQLite/in-memory store backends.
  • CLI-driven operations and localized output.
  • CLI attachment-aware recording (record-with-attachments) with bounded file and inline attachment inputs.
  • CLI Decision Gate fixture ingest command path wired to production adapter implementation.
  • System-test harness with registry-driven coverage, including OpenClaw gateway/CLI mock-flow and Decision Gate runpack-flow adapter-ingest integration tests.
  • 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 success/strict-fail paths.
  • Production Decision Gate adapter crate (crates/arxi-decision-gate-adapter) with deterministic MCP/runpack mapping, runpack-integrity strict/anomaly policy handling, and transcript redaction/bounds controls.
  • OpenClaw integration harness mapping policy with deterministic sensitive-field redaction and bounded payload handling for fixture-driven coupling tests.
  • Decision Gate integration system-tests wired to the production adapter crate, covering signed/unsigned lanes, root-hash and manifest-integrity mismatch fail-closed behavior, and deterministic replay/hash stability.
  • Sidecar Docker operator profile (docker/sidecar) and system-test coverage for Dockerfile/Compose hardening plus containerized probe/open/record/query flow.
  • Sidecar readiness semantics now support fail-closed dependency modes: storage-only readiness and storage+enterprise-control readiness.

Current post-core gaps in system-level behavior:

  • P2 stress/performance system-test expansion remains open.
  • Sidecar release-grade perf/soak promotion remains opt-in via ARXI_SIDECAR_PERF_GATE=1 and still requires CI profile tuning.

Recently closed system-level hardening items:

File-by-File Cross Reference

AreaFileNotes
Workspace boundariesCargo.tomlCrate membership and lint posture.
Core contractscrates/arxi-core/src/lib.rsShared domain primitives and traits.
Envelope modelcrates/arxi-envelope/src/lib.rsEvidence data model and contracts.
Recorder runtimecrates/arxi-recorder/src/engine.rsIngest, chain progression, segment lifecycle.
Bundle + verifiercrates/arxi-recorder/src/bundle_builder.rsSelector resolution and bundle materialization.
Bundle verificationcrates/arxi-recorder/src/verifier.rs7-phase offline verification.
Storage traitscrates/arxi-store/src/traits.rsPersistence contract invariants.
SQLite queue boundarycrates/arxi-store/src/sqlite/connection.rsBounded async-to-sync dispatch and saturation fail-closed behavior.
CLI surfacecrates/arxi-cli/src/main.rs, crates/arxi-cli/src/commands.rs, crates/arxi-cli/src/support.rsOperational command architecture split across dispatch, command handlers, and runtime/utility helpers.
Sidecar servicecrates/arxi-sidecar/src/lib.rs, crates/arxi-sidecar/src/server.rsHTTP runtime, middleware stack, and transport lifecycle.
Sidecar config/securitycrates/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.rsFail-closed config validation and projection authority plus sidecar auth/bounds controls and persistent idempotency behavior.
Sidecar container packagingdocker/sidecar/Dockerfile, docker/sidecar/docker-compose.yml, docker/sidecar/config/sidecar.tomlFirst-party container build/runtime profile aligned to sidecar validation/security invariants.
Contract generatorcrates/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.rsDeterministic generated artifact authority + drift checks.
System-testssystem-tests/README.mdEnd-to-end validation contract.
Decision Gate adaptercrates/arxi-decision-gate-adapter/src/adapter.rsProduction mapping/redaction/integrity policy implementation for Decision Gate ingest.
OpenClaw integration testssystem-tests/tests/suites/integration_openclaw.rsFixture-driven adapter ingest verification for external workflow coupling.
OpenClaw integration architectureDocs/architecture/arxi_openclaw_integration_architecture.mdVersioned mapping and redaction/bounded payload policy contract.
Decision Gate integration testssystem-tests/tests/suites/integration_decision_gate.rsFixture-driven MCP runpack flow ingest verification for control-plane coupling.
Decision Gate integration architectureDocs/architecture/arxi_decision_gate_integration_architecture.mdVersioned MCP flow mapping, runpack integrity policy, and transcript redaction/bounds contract.