README.md

---
license: mit
tags:
- agent
- ai-agents
- logging
- audit
- tamper-evident
- observability
- mcp
- llm-agents
- compliance
---

# arcaeon-ledger

**Observability tools show you what your agent did. This lets you *prove* it.**

Every record is hash-chained to the one before it. Edit a row, delete one, or
reorder history, and every later link breaks — `verify()` names the exact
line. You own the record, on your own disk, and you can prove it wasn't
altered. Zero dependencies, one JSONL file, two verbs.

## Install

```
pip install arcaeon-ledger
```

## Verify it yourself in 30 seconds

```bash
python -m arcaeon_ledger.cli append demo.jsonl '{"tool":"search","ok":true}'
python -m arcaeon_ledger.cli append demo.jsonl '{"tool":"payment","amount":"49.00"}'
python -m arcaeon_ledger.cli verify demo.jsonl        # exit 0 -- chain intact

# now flip one byte by hand: open demo.jsonl, change "49.00" to "94.00", save
python -m arcaeon_ledger.cli verify demo.jsonl        # exit 1 -- names the broken line
```

Or skip the manual edit and run the frozen, golden-vector self-test suite
directly — it plants the tamper for you and asserts the exact failure:

```
python -m arcaeon_ledger.selftest
```

## Non-proofs — read this before the features

Being precise here is the product, not a disclaimer. A hash chain proves the
recorded bytes weren't altered *in place* after writing. It does **not**, by
itself, prove three other things:

1. **Truncation.** Lop off the most recent rows and what remains verifies
   clean. Close it with `head()` + a witness (below) on a cadence.
2. **Truth.** The chain notarizes whatever was written — a tamper-evident
   record of a hallucination is still a hallucination with a checksum.
   `bind_artefact()` hashes a re-fetchable source so a third party can check it.
3. **Authorship.** `authority()` records who-claimed-what as data in the row,
   not a signature — a rewriter who re-mints from genesis re-mints it too.

Scoped honestly, the primitive is *"this file was not rewritten in
place"* — small, true, and testable. Everything below is a layer you add on
top, stated, not implied.

## What it does

```python
from arcaeon_ledger import Ledger

log = Ledger("agent.log.jsonl")
log.append({"tool": "web.search", "query": "weather in LA", "result_ok": True})
log.verify()          # VerifyResult(ok=True, rows=1, chained=1, ...)
```

- **`authority()`** binds an actor + their permission surface into the
  chained row — sharpens "was this edited?" into "was this edited *and* was
  the writer authorized?"
- **`bind_artefact()` / `verify_artefact()`** hash the actual bytes an agent
  read (a URL, a file, a dict) so a stranger can re-fetch and compare —
  honestly reported as `match` / `mismatch` / `unavailable`, never overclaimed
  as proof of tampering on a mismatch (the web mutates and 404s on its own).
- **`WitnessStore` / `publish_head()` / `verify_against_witness()`** — an
  external witness that pins your `(rows, chain)` on a cadence, so truncation
  and re-minting both fail against the last pin. The max gap between pins is
  your real security parameter, not the average.
- **MCP server** — `python -m arcaeon_ledger.mcp_server --log agent.log.jsonl`
  gives any MCP client two tools: `ledger_append` and `ledger_verify`. No SDK.
- **CLI** — `append` / `verify`, wired into CI or a pre-ship gate; a tampered
  log exits nonzero.

## Status

Core library, CLI, and MCP server, all tested against edit/delete/reorder
tampering plus a full MCP wire handshake. Extracted from a hash-chained
action ledger running in production.

## Links

- **PyPI:** [pypi.org/project/arcaeon-ledger](https://pypi.org/project/arcaeon-ledger/)
- **Source:** [github.com/dan8433-user/ledger](https://github.com/dan8433-user/ledger)
- **Org / other Arcaeon repos:** [github.com/Arcaeon-io](https://github.com/Arcaeon-io)
- **Verify us, don't take our word for it:** [arcaeon.io/verify](https://arcaeon.io/verify)
- **Live demo:** [Arcaeon/tamper-evidence-demo](https://huggingface.co/spaces/Arcaeon/tamper-evidence-demo)

MIT. Built by [Arcaeon](https://arcaeon.io) — the evidence layer for AI.