Arxi Decision Gate Asset Core
Docs
Arxi Docs

Proof recording and tamper-evident evidence documentation.

Other product docs

Arxi Evidence Model and Integrity Architecture

Audience: Engineers implementing envelope ingestion, hashing, signing, and integrity verification.

Table of Contents

  1. Executive Overview
  2. Identity and Schema Primitives
  3. Envelope and Segment Model
  4. Canonical Encoding and Hashing
  5. Attachment Integrity
  6. Signature Model
  7. Verification Result Algebra
  8. File-by-File Cross Reference

Executive Overview

Arxi integrity is built on canonical bytes plus cryptographic linkage:

  • envelope content hashes over canonicalized 11-field hashable views,
  • chain hashes linking each envelope to prior state,
  • segment genesis and predecessor chain-head linkage,
  • optional envelope signatures over content-hash bytes.

F:crates/arxi-envelope/src/envelope.rs L46-L92 F:crates/arxi-envelope/src/encoding.rs L252-L296 F:crates/arxi-envelope/src/segment.rs L39-L66

Identity and Schema Primitives

  • UUIDv7-backed IDs: EnvelopeId, SegmentId, BundleId.
  • String IDs with validation: EventType, ActorId, EnvironmentId, etc.
  • String-backed IDs fail closed on empty, whitespace-only, and control-character input.
  • String-backed IDs enforce explicit max-length bounds (256 for trace/session/actor/environment, 128 for event/adapter IDs).
  • String-backed ID serde paths are constructor-validated so hostile JSON cannot bypass invariants.
  • KeyId is strict canonical lowercase hex(SHA-256(public_key_bytes)) (64 chars).
  • SchemaVersion is explicit and currently pinned to 1 (CURRENT_SCHEMA_VERSION).

F:crates/arxi-core/src/identity.rs L31-L55 F:crates/arxi-core/src/identity.rs L205-L647 F:crates/arxi-core/src/schema.rs L24-L49

Envelope and Segment Model

Envelope states

  • UnsealedEnvelope: adapter-supplied hashable fields.
  • Envelope: recorder-sealed record with content_hash, chain_hash, sequence, segment_id, and optional signature.

F:crates/arxi-envelope/src/envelope.rs L98-L131 F:crates/arxi-envelope/src/envelope.rs L46-L92

Builder invariants

EnvelopeBuilder enforces required fields, UTC claimed time, and deterministic attachment ordering before producing an UnsealedEnvelope. F:crates/arxi-envelope/src/envelope.rs L284-L328

Segment structure

SegmentGenesis is structural metadata (not an envelope) and anchors first-chain computation; predecessor fields must be jointly set or absent. recorder_id is bounded by the same max length as ActorId and deserialize paths are constructor-validated. F:crates/arxi-envelope/src/segment.rs L39-L109

SealRecord captures final segment state and SealReason taxonomy. F:crates/arxi-envelope/src/segment.rs L116-L170

Canonical Encoding and Hashing

Arxi uses JCS (serde_jcs) over private hashable view structs. Important invariants:

  • None is serialized as null in canonical output.
  • timestamps use fixed 9-digit nanosecond UTC format.
  • attachment refs are sorted by hash hex in canonical views.

F:crates/arxi-envelope/src/encoding.rs L19-L31 F:crates/arxi-envelope/src/encoding.rs L48-L77 F:crates/arxi-envelope/src/encoding.rs L148-L162

Hash model:

  • content_hash = H(canonical_bytes)
  • chain_hash = H(prev_chain_hash || content_hash)
  • first envelope in segment uses H(segment_genesis_hash || content_hash)

F:crates/arxi-envelope/src/encoding.rs L239-L246 F:crates/arxi-envelope/src/encoding.rs L262-L273 F:crates/arxi-envelope/src/encoding.rs L285-L296

Hash functions are algorithm-identified and pluggable through HashFunction. Current default is Sha256HashFunction. F:crates/arxi-core/src/hash.rs L200-L274

Attachment Integrity

Two attachment representations:

  • AttachmentData: inline bytes submitted at ingest.
  • AttachmentRef: content-addressed metadata embedded in envelopes.

AttachmentRef and AttachmentData reject empty, whitespace-only, and control-character-bearing content_type values, enforce max length (255), and deserialize AttachmentRef through constructor validation. AttachmentData also requires non-empty bytes. F:crates/arxi-envelope/src/attachment.rs L35-L85 F:crates/arxi-envelope/src/attachment.rs L99-L133

Signature Model

Core contract:

  • EnvelopeSigner signs content_hash bytes.
  • SignatureVerifier verifies message bytes under algorithm-specific keys.
  • TrustRoot and TrustPolicy define trusted key material and signature acceptance policy (AnyTrustedKey, AllMustSign, Threshold).

F:crates/arxi-core/src/signature.rs L131-L270 F:crates/arxi-core/src/signature.rs L301-L337

Current implementation:

Verification Result Algebra

arxi-envelope defines verification data types, while algorithmic verification runs in arxi-recorder.

Key structures:

  • VerificationManifest and ManifestSegmentEntry
  • VerificationVerdict and VerdictStatus
  • CheckResult, CheckType, and specialized chain/cross-segment/signature checks
  • VerificationWarning for non-fatal findings

F:crates/arxi-envelope/src/verification.rs L39-L79 F:crates/arxi-envelope/src/verification.rs L85-L132 F:crates/arxi-envelope/src/verification.rs L189-L266

File-by-File Cross Reference

AreaFileNotes
Identity contractscrates/arxi-core/src/identity.rsID validation and serialization-stable newtypes.
Hash contractscrates/arxi-core/src/hash.rsHash types, constant-time equality, algorithm registry.
Signature contractscrates/arxi-core/src/signature.rsSigner/verifier traits and envelope signature shape.
Envelope modelcrates/arxi-envelope/src/envelope.rsSealed/unsealed forms and builder invariants.
Canonical encodingcrates/arxi-envelope/src/encoding.rsJCS canonical bytes and chain formulas.
Segment modelcrates/arxi-envelope/src/segment.rsGenesis and seal metadata.
Attachmentscrates/arxi-envelope/src/attachment.rsContent-addressed attachment references.
Verification modelcrates/arxi-envelope/src/verification.rsVerdict and check-result algebra.
Ed25519 verifycrates/arxi-envelope/src/signature.rsStrict signature verification implementation.
Ed25519 signcrates/arxi-envelope/src/signer.rsEnvelope signing implementation.