Metadata-Version: 2.5
Name: argus-ledger
Version: 0.1.0a2
Summary: Tamper-evident append-only SHA-256 provenance and audit ledger for autonomous agents.
Project-URL: Homepage, https://github.com/Perseus-Computing-LLC/argus
Project-URL: Repository, https://github.com/Perseus-Computing-LLC/argus
Author-email: Perseus Computing LLC <contact@perseuscomputing.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# argus-ledger

> Append-only SHA-256 audit log for autonomous agents.

[![Crates.io](https://img.shields.io/crates/v/argus-ledger.svg)](https://crates.io/crates/argus-ledger)
[![docs.rs](https://docs.rs/argus-ledger/badge.svg)](https://docs.rs/argus-ledger)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.85-informational.svg)](Cargo.toml)

Part of the **Telarch Suite** (TCI / Telarch Cognitive Infrastructure) by [Perseus Computing LLC](https://github.com/Perseus-Computing-LLC).

---

## Why Argus exists

When autonomous agents run shell commands, call APIs, or mutate files, you need a reliable record of what happened and proof that logs were not changed after the fact.

Argus records every event into an append-only sequence where each entry includes the SHA-256 hash of the previous record. If any entry is altered or deleted, verification fails immediately and points directly to the modified index.

---

## Key design goals

- **Continuous hash chaining:** Every event links cryptographically to the one before it, rooted at genesis.
- **Fail-closed tamper detection:** Verifies cryptographic continuity and aborts immediately when any hash or payload is corrupted. Tampered event #42 is detected in ~46.5 &micro;s.
- **Low latency appends:** In-memory sequential appends with SHA-256 chaining execute at ~600,000 events/s (~1.67 &micro;s/event).
- **High throughput chain verification:** Traverses and validates complete cryptographic sequences at ~839,000 events/s (~1.19 &micro;s/event).
- **Self-contained:** Runs fully offline as an in-memory library without external audit services or cloud dependencies.

---

## Installation

Add `argus-ledger` to your `Cargo.toml`:

```toml
[dependencies]
argus-ledger = "0.1.0-alpha.2"
```

Or via Cargo:

```bash
cargo add argus-ledger
```

---

## Example

```rust
use argus_ledger::{
    AuditLedgerReader, AuditLedgerWriter, AuditVerifier, InMemoryLedger,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut ledger = InMemoryLedger::new();

    // 1. Record agent startup
    let ev1 = ledger.append(
        "AGENT_BOOTSTRAP",
        "runtime:node_0",
        r#"{"model":"qwen2.5-coder-32b","temperature":0.2}"#,
    )?;
    println!("Sequence #{}: Hash {}", ev1.sequence, &ev1.event_hash[0..16]);

    // 2. Record tool execution
    let ev2 = ledger.append(
        "TOOL_INVOCATION",
        "runtime:node_0",
        r#"{"tool":"terminal","command":"cargo test --workspace"}"#,
    )?;
    println!("Sequence #{}: Hash {}", ev2.sequence, &ev2.event_hash[0..16]);

    // 3. Verify cryptographic integrity
    let report = ledger.verify_chain()?;
    assert!(report.valid, "Chain integrity compromised");
    println!(
        "Chain verified intact: {} blocks validated across sequence.",
        report.total_events
    );

    Ok(())
}
```

---

## Python: keyed signing (optional)

An unkeyed hash chain detects an edit to one record, but someone who can write the file can rewrite every later hash and still pass. Give the ledger a key and each event also carries an HMAC-SHA256 signature; the same rewrite then fails at the first forged event.

```python
from argus_ledger import AppendOnlyLedger

key = AppendOnlyLedger.load_key("/secure/location/argus.key")   # refuses a key file others can read
ledger = AppendOnlyLedger("audit.jsonl", signing_key=key, require_signature=True)
ledger.append("tool_execution", "agent", {"tool": "terminal"})
assert ledger.verify_chain().valid
```

The ledger file is created owner-only (0600). Keep the key somewhere an attacker with write access to the ledger cannot also reach. Ledgers written without a key still verify without one; with a key configured, unsigned events fail.

## Benchmark results

Measured on bare-metal Linux x86_64 (`rustc 1.85.0`, `opt-level = 3`, `lto = "fat"`):

| Metric | Measurement | Test condition | Operational Guarantee |
| :--- | :--- | :--- | :--- |
| **Append Throughput (1M Events)** | **632,170 events/s** | 1,000,000 sequential events (`argus_1m_scale`) | 1.58 &micro;s / event continuous SHA-256 chaining |
| **Linear Verification (1M Events)** | **770,758 events/s** | Full 1M event SHA-256 hash chain validation | 1.30 &micro;s / event; validates 1M events in 1.29 s |
| **Tamper Detection (Sequence #500,000)** | **640.48 ms** | Mid-chain single-bit payload corruption | Fail-closed immediate abort and offset isolation |
| **Micro-Audit Latency (Block #42)** | **46.50 &micro;s** | Short sequence microbenchmark | Sub-50 µs early tamper detection |
| **Tamper Detection Sensitivity** | **100.00%** | Single-bit byte flip sensitivity | Mathematical immutability guarantee |
| **External Dependencies** | **0** | Standalone offline primitives | Zero network, zero remote cloud requirement |

Run benchmarks yourself:

```bash
cargo run --release -p telarch-benchmarks
cargo run --release -p telarch-benchmarks --bin argus_1m_scale
```

---

## License

Copyright &copy; 2026 Perseus Computing LLC. Released under the [MIT License](LICENSE).
