Fix source link: point at the actual public repo (dan8433-user/ledger), not the org page

4f9db3f verified 2 days ago

4.16 kB

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

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:

Truncation. Lop off the most recent rows and what remains verifies clean. Close it with head() + a witness (below) on a cadence.
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.
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

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.

Arcaeon
/

arcaeon-ledger