arcaeon-ledger 0.2.0__tar.gz

arcaeon_ledger-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.log.jsonl
+.venv/

arcaeon_ledger-0.2.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0 — 2026-08-12
+- Added `authority()` helper + `append(..., authority=...)`: bind WHO wrote each entry and with what permission (resolved principal, capability version, hashed tool schema, trusted time source). It chains like any field, so editing the writer identity breaks the chain too. Composes tamper-evidence with permission-replay. Shipped same-day in response to community feedback on launch.
+
+
+## 0.1.0 — 2026-08-12
+- Initial release. Zero-dependency tamper-evident, hash-chained action log for AI agents.
+- Core library: `Ledger(path).append(record)` and `.verify()`; module `verify_file(path)`.
+- Hash chain: `sha256(prev_chain + canonical_json(row_without_chain))[:32]`, genesis-seeded, atomic append (append-binary + flush + fsync).
+- CLI: `ledger verify|append` with nonzero exit on a broken chain (CI/pre-ship gate).
+- MCP server (`python -m ledger.mcp_server`): drop-in `ledger_append` / `ledger_verify` tools for any MCP client, zero-dependency JSON-RPC over stdio.
+- Tested against edit, delete, and reorder tampering, and a full MCP handshake including tamper detection over the wire.

arcaeon_ledger-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcaeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcaeon_ledger-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: arcaeon-ledger
+Version: 0.2.0
+Summary: Tamper-evident, hash-chained action log for AI agents. Prove what your agent did.
+Project-URL: Homepage, https://arcaeon.io
+Author: Arcaeon
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,hash-chain,mcp,provenance,tamper-evident
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ledger
+
+**Observability tools show you what your agent did. `ledger` 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, and you can prove it wasn't altered. Zero dependencies, one
+JSONL file, two verbs.
+
+```python
+from ledger import Ledger
+
+log = Ledger("agent.log.jsonl")
+log.append({"tool": "web.search", "query": "weather in LA", "result_ok": True})
+log.append({"tool": "payment", "amount": "49.00", "currency": "USD"})
+
+log.verify()          # VerifyResult(ok=True, rows=2, chained=2, ...)
+```
+
+Tampering is caught, not hoped against:
+
+```python
+# someone edits row 1's amount in the file by hand...
+log.verify()          # VerifyResult(ok=False, first_break="line 1: chain mismatch")
+```
+
+CLI (wire it into CI or a pre-ship gate — a tampered log exits nonzero):
+
+```
+python -m ledger.cli append agent.log.jsonl '{"tool":"search","ok":true}'
+python -m ledger.cli verify agent.log.jsonl        # exit 0 = intact, 1 = broken
+```
+
+## Prove *who* acted, not just the order
+
+A hash chain proves sequence integrity — it can't prove who wrote each entry or
+whether they were allowed to. Attach an `authority` block to bind the actor and
+their permission surface into the chained (tamper-evident) row:
+
+```python
+from ledger import Ledger, authority
+
+log = Ledger("agent.log.jsonl")
+log.append(
+    {"tool": "payment", "amount": "49.00"},
+    authority=authority(
+        "agent://billing-7",
+        capability_version="v3",              # what they were allowed to do
+        tool_schema={"name": "payment", "args": ["amount"]},  # hashed, not just named
+        time_source="ntp",                    # trust surface of the clock
+    ),
+)
+```
+
+Now the audit question sharpens from *"was this edited?"* to *"was this edited
+**and** was the writer authorized?"* — editing the principal, capability, or
+schema hash breaks the chain like any other tamper. This composes tamper-evidence
+with permission-replay. (Shipped in response to community feedback on launch.)
+
+## Why this exists
+
+The loudest unmet pain for agent builders in 2026 is the reliability/audit gap:
+an agent "completes" a task and the result is quietly wrong, and you can't
+reconstruct — or prove — what actually happened. Observability platforms trace
+runs; none give you a **tamper-evident, portable, ownable** record. Regulations
+(EU AI Act Art. 12, tamper-evident AI decision records) are starting to require
+exactly this. `ledger` is the smallest honest version: a cryptographically
+chained action log you drop in, own, and verify.
+
+## How the chain works
+
+`chain = sha256(prev_chain + canonical_json(row_without_chain))[:32]`
+
+Each row commits to the entire history before it. The first row chains from a
+fixed `"genesis"` seed. Rows without a `chain` field are tolerated only before
+the first chained row (so you can adopt it on an existing log); an unchained row
+appearing *after* the chain begins is itself flagged. On a mismatch, verify
+keeps going from the claimed value so it counts later damage honestly instead of
+cascading one break into noise.
+
+The honest limit: `ledger` proves a file wasn't altered *after* writing. It does
+not prove the writer was honest at write time, and it does not by itself defend
+against someone who rewrites the whole chain from a chosen point forward — for
+that you periodically anchor the latest chain value somewhere you don't control
+(a commit, a timestamp service, a witness). That anchoring is on the roadmap;
+the core tamper-evidence is here and tested.
+
+## Drop it into any MCP agent
+
+`ledger` ships a zero-dependency MCP server, so any MCP client (Claude Code,
+etc.) can give its agent tamper-evident logging with no code. Wire it in:
+
+```json
+{
+  "mcpServers": {
+    "ledger": {
+      "command": "python",
+      "args": ["-m", "ledger.mcp_server", "--log", "agent.log.jsonl"]
+    }
+  }
+}
+```
+
+The agent then has two tools: `ledger_append(record)` to log an action
+(returns its chain hash) and `ledger_verify()` to prove the whole log is
+intact (or get the exact tampered line back). MCP is JSON-RPC over stdio and
+this server speaks it directly — no SDK, no extra install.
+
+## Status
+
+Core library, CLI, and a drop-in **MCP server**, all tested: the library
+against edit / delete / reorder tampering (`test_ledger.py`), the MCP server
+through a full initialize → tools/list → append → verify handshake including
+tamper detection over the wire. Extracted from a hash-chained action ledger
+running in production. A hosted collection tier (retention + compliance export)
+and periodic external anchoring are the next layers.
+
+MIT.

arcaeon_ledger-0.2.0/README.md

@@ -0,0 +1,118 @@
+# ledger
+
+**Observability tools show you what your agent did. `ledger` 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, and you can prove it wasn't altered. Zero dependencies, one
+JSONL file, two verbs.
+
+```python
+from ledger import Ledger
+
+log = Ledger("agent.log.jsonl")
+log.append({"tool": "web.search", "query": "weather in LA", "result_ok": True})
+log.append({"tool": "payment", "amount": "49.00", "currency": "USD"})
+
+log.verify()          # VerifyResult(ok=True, rows=2, chained=2, ...)
+```
+
+Tampering is caught, not hoped against:
+
+```python
+# someone edits row 1's amount in the file by hand...
+log.verify()          # VerifyResult(ok=False, first_break="line 1: chain mismatch")
+```
+
+CLI (wire it into CI or a pre-ship gate — a tampered log exits nonzero):
+
+```
+python -m ledger.cli append agent.log.jsonl '{"tool":"search","ok":true}'
+python -m ledger.cli verify agent.log.jsonl        # exit 0 = intact, 1 = broken
+```
+
+## Prove *who* acted, not just the order
+
+A hash chain proves sequence integrity — it can't prove who wrote each entry or
+whether they were allowed to. Attach an `authority` block to bind the actor and
+their permission surface into the chained (tamper-evident) row:
+
+```python
+from ledger import Ledger, authority
+
+log = Ledger("agent.log.jsonl")
+log.append(
+    {"tool": "payment", "amount": "49.00"},
+    authority=authority(
+        "agent://billing-7",
+        capability_version="v3",              # what they were allowed to do
+        tool_schema={"name": "payment", "args": ["amount"]},  # hashed, not just named
+        time_source="ntp",                    # trust surface of the clock
+    ),
+)
+```
+
+Now the audit question sharpens from *"was this edited?"* to *"was this edited
+**and** was the writer authorized?"* — editing the principal, capability, or
+schema hash breaks the chain like any other tamper. This composes tamper-evidence
+with permission-replay. (Shipped in response to community feedback on launch.)
+
+## Why this exists
+
+The loudest unmet pain for agent builders in 2026 is the reliability/audit gap:
+an agent "completes" a task and the result is quietly wrong, and you can't
+reconstruct — or prove — what actually happened. Observability platforms trace
+runs; none give you a **tamper-evident, portable, ownable** record. Regulations
+(EU AI Act Art. 12, tamper-evident AI decision records) are starting to require
+exactly this. `ledger` is the smallest honest version: a cryptographically
+chained action log you drop in, own, and verify.
+
+## How the chain works
+
+`chain = sha256(prev_chain + canonical_json(row_without_chain))[:32]`
+
+Each row commits to the entire history before it. The first row chains from a
+fixed `"genesis"` seed. Rows without a `chain` field are tolerated only before
+the first chained row (so you can adopt it on an existing log); an unchained row
+appearing *after* the chain begins is itself flagged. On a mismatch, verify
+keeps going from the claimed value so it counts later damage honestly instead of
+cascading one break into noise.
+
+The honest limit: `ledger` proves a file wasn't altered *after* writing. It does
+not prove the writer was honest at write time, and it does not by itself defend
+against someone who rewrites the whole chain from a chosen point forward — for
+that you periodically anchor the latest chain value somewhere you don't control
+(a commit, a timestamp service, a witness). That anchoring is on the roadmap;
+the core tamper-evidence is here and tested.
+
+## Drop it into any MCP agent
+
+`ledger` ships a zero-dependency MCP server, so any MCP client (Claude Code,
+etc.) can give its agent tamper-evident logging with no code. Wire it in:
+
+```json
+{
+  "mcpServers": {
+    "ledger": {
+      "command": "python",
+      "args": ["-m", "ledger.mcp_server", "--log", "agent.log.jsonl"]
+    }
+  }
+}
+```
+
+The agent then has two tools: `ledger_append(record)` to log an action
+(returns its chain hash) and `ledger_verify()` to prove the whole log is
+intact (or get the exact tampered line back). MCP is JSON-RPC over stdio and
+this server speaks it directly — no SDK, no extra install.
+
+## Status
+
+Core library, CLI, and a drop-in **MCP server**, all tested: the library
+against edit / delete / reorder tampering (`test_ledger.py`), the MCP server
+through a full initialize → tools/list → append → verify handshake including
+tamper detection over the wire. Extracted from a hash-chained action ledger
+running in production. A hosted collection tier (retention + compliance export)
+and periodic external anchoring are the next layers.
+
+MIT.

arcaeon_ledger-0.2.0/ledger/__init__.py

@@ -0,0 +1,197 @@
+"""ledger — a tamper-evident, append-only action log for AI agents.
+
+Observability tools show you what your agent did. `ledger` lets you PROVE it:
+every record is hash-chained to the one before it, so an edit, deletion, or
+reorder anywhere in the history breaks every later link and `verify()` names the
+exact line. Own the record; prove it wasn't altered.
+
+Zero dependencies (stdlib only). One JSONL file. Two verbs: append, verify.
+
+    from ledger import Ledger
+    log = Ledger("agent.log.jsonl")
+    log.append({"tool": "search", "query": "weather", "result_ok": True})
+    log.verify()          # -> VerifyResult(ok=True, rows=1, ...)
+
+Extracted from a hash-chained action ledger running in production. MIT.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+
+__version__ = "0.2.0"
+__all__ = ["Ledger", "VerifyResult", "verify_file", "authority"]
+
+_GENESIS = "genesis"
+_CHAIN_LEN = 32  # first N hex chars of the sha256 — plenty for tamper-evidence
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _chain(prev: str, obj: dict) -> str:
+    """chain = sha256(prev_chain + canonical-json-of-row-without-chain)."""
+    body = json.dumps({k: v for k, v in obj.items() if k != "chain"},
+                      ensure_ascii=False, sort_keys=True)
+    return hashlib.sha256((prev + body).encode("utf-8")).hexdigest()[:_CHAIN_LEN]
+
+
+def authority(principal: str, *, capability_version: str | None = None,
+              tool_schema: Any = None, time_source: str = "local") -> dict:
+    """Build an `authority` block for an entry: WHO acted, with what authority.
+
+    A hash chain proves ORDER, not who wrote each entry or whether they were
+    allowed to. Attaching this block makes the audit question sharper — "was
+    this edited?" becomes "was this edited AND was the writer authorized?" —
+    and lets tamper-evidence compose with permission-replay. (Requested by the
+    community on launch, 2026-08-12.)
+
+    - principal: the resolved actor (agent id, user, service).
+    - capability_version: the version of the permission/capability set in force.
+    - tool_schema: the tool's schema/signature — HASHED, so you bind what the
+      tool looked like at call time, not just its name.
+    - time_source: where the timestamp came from (e.g. "local", "ntp", an
+      external attestation id). Names the trust surface of the clock.
+    """
+    block: dict[str, Any] = {"principal": principal, "time_source": time_source}
+    if capability_version is not None:
+        block["capability_version"] = capability_version
+    if tool_schema is not None:
+        canon = json.dumps(tool_schema, ensure_ascii=False, sort_keys=True)
+        block["tool_schema_hash"] = hashlib.sha256(canon.encode("utf-8")).hexdigest()[:16]
+    return block
+
+
+@dataclass
+class VerifyResult:
+    ok: bool
+    rows: int = 0
+    chained: int = 0
+    prechain: int = 0
+    first_break: str | None = None
+
+    def __bool__(self) -> bool:  # `if log.verify(): ...`
+        return self.ok
+
+
+class Ledger:
+    """A hash-chained append-only JSONL log. One file, atomic appends."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+
+    # -- write --------------------------------------------------------------
+    def append(self, record: dict[str, Any], *, authority: dict | None = None) -> str:
+        """Append one record; returns its chain hash. Stamps `ts` if absent.
+
+        Pass `authority=` (build it with the module-level `authority()` helper)
+        to bind WHO wrote the entry and with what permission — it becomes part
+        of the chained, tamper-evident row, so the authority surface is proven
+        alongside the order.
+
+        Atomic: append-binary + flush + fsync, so a crash mid-write never
+        corrupts the file (a partial line fails to parse and is caught by
+        verify, it never silently poisons the chain).
+        """
+        obj = dict(record)
+        if authority is not None:
+            obj["authority"] = authority
+        obj.setdefault("ts", _now_iso())
+        obj.pop("chain", None)
+        obj["chain"] = _chain(self._last_chain(), obj)
+        line = json.dumps(obj, ensure_ascii=False) + "\n"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("ab") as fh:
+            fh.write(line.encode("utf-8"))
+            fh.flush()
+            try:
+                os.fsync(fh.fileno())
+            except OSError:
+                pass  # network mounts may not support fsync; flush is the floor
+        return obj["chain"]
+
+    def _last_chain(self) -> str:
+        """Chain of the last row ('genesis' if empty/missing). Tail-read only."""
+        try:
+            with self.path.open("rb") as fh:
+                fh.seek(0, os.SEEK_END)
+                size = fh.tell()
+                fh.seek(max(0, size - 8192))
+                tail = fh.read().decode("utf-8", errors="replace")
+        except OSError:
+            return _GENESIS
+        for raw in reversed(tail.splitlines()):
+            raw = raw.strip()
+            if not raw:
+                continue
+            try:
+                return json.loads(raw).get("chain") or _GENESIS
+            except ValueError:
+                continue
+        return _GENESIS
+
+    # -- read ---------------------------------------------------------------
+    def __iter__(self) -> Iterator[dict]:
+        try:
+            for raw in self.path.read_text(encoding="utf-8",
+                                           errors="replace").splitlines():
+                raw = raw.strip()
+                if raw:
+                    try:
+                        yield json.loads(raw)
+                    except ValueError:
+                        continue
+        except OSError:
+            return
+
+    # -- verify -------------------------------------------------------------
+    def verify(self) -> VerifyResult:
+        return verify_file(self.path)
+
+
+def verify_file(path: str | Path) -> VerifyResult:
+    """Recompute the chain over a file; report the first break by line number.
+
+    Rows with no `chain` field are tolerated ONLY before the first chained row
+    (legacy/pre-chain history) — an unchained row appearing after the chain has
+    begun is itself a tamper signal. On a mismatch, verification continues from
+    the CLAIMED value so later damage is counted honestly rather than cascading.
+    """
+    res = VerifyResult(ok=True)
+    try:
+        lines = Path(path).read_text(encoding="utf-8", errors="replace").splitlines()
+    except OSError as e:
+        return VerifyResult(ok=False, first_break=f"unreadable: {e}")
+    prev = _GENESIS
+    for i, raw in enumerate(lines, 1):
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            obj = json.loads(raw)
+        except ValueError:
+            res.ok = False
+            res.first_break = res.first_break or f"line {i}: unparseable"
+            continue
+        res.rows += 1
+        claimed = obj.pop("chain", None)
+        if claimed is None:
+            if res.chained:
+                res.ok = False
+                res.first_break = res.first_break or f"line {i}: unchained row after chain began"
+            else:
+                res.prechain += 1
+            continue
+        want = _chain(prev, obj)
+        if claimed != want:
+            res.ok = False
+            res.first_break = res.first_break or f"line {i}: chain mismatch"
+        prev = claimed
+        res.chained += 1
+    return res

arcaeon_ledger-0.2.0/ledger/cli.py

@@ -0,0 +1,45 @@
+"""ledger CLI — verify or append from the command line.
+
+    python -m ledger.cli verify agent.log.jsonl
+    python -m ledger.cli append agent.log.jsonl '{"tool":"search","ok":true}'
+
+Exit code 0 = chain intact, 1 = broken (or bad usage). The nonzero exit is the
+point: wire `verify` into CI or a pre-ship gate and a tampered log fails loud.
+"""
+from __future__ import annotations
+
+import json
+import sys
+
+from ledger import Ledger, verify_file
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) < 2 or argv[0] not in ("verify", "append"):
+        print((__doc__ or "usage: ledger verify|append <path> [record]").strip())
+        return 1
+    cmd, path = argv[0], argv[1]
+    if cmd == "verify":
+        r = verify_file(path)
+        print(json.dumps(r.__dict__, indent=1))
+        return 0 if r.ok else 1
+    # append
+    if len(argv) < 3:
+        print("append needs a JSON record argument")
+        return 1
+    try:
+        record = json.loads(argv[2])
+    except ValueError as e:
+        print(f"bad JSON: {e}")
+        return 1
+    if not isinstance(record, dict):
+        print("record must be a JSON object")
+        return 1
+    chain = Ledger(path).append(record)
+    print(chain)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

arcaeon_ledger-0.2.0/ledger/mcp_server.py

@@ -0,0 +1,130 @@
+"""ledger MCP server — drop-in tamper-evident logging for any MCP agent.
+
+Zero dependencies: MCP is JSON-RPC 2.0 over stdio, so this speaks it directly
+rather than pulling the SDK (keeps the whole product install-free). Any MCP
+client (Claude Code, etc.) can wire it in and its agent gets two tools:
+
+  ledger_append(record)  -> chain hash   (log an action, tamper-evidently)
+  ledger_verify()        -> verify result (prove the log wasn't altered)
+
+Run:  python -m ledger.mcp_server [--log PATH]
+Wire into an MCP client (e.g. Claude Code .mcp.json):
+  { "mcpServers": { "ledger": {
+      "command": "python", "args": ["-m", "ledger.mcp_server", "--log", "agent.log.jsonl"] } } }
+
+Implements the slice of MCP a tool server needs: initialize, tools/list,
+tools/call. Protocol version 2025-06-18. Notifications are ignored (no id).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from ledger import Ledger
+
+PROTOCOL_VERSION = "2025-06-18"
+
+TOOLS = [
+    {
+        "name": "ledger_append",
+        "description": ("Append one action record to a tamper-evident, hash-chained "
+                        "log. Returns the record's chain hash. Use this to log every "
+                        "consequential action (tool calls, payments, decisions) so the "
+                        "history can later be proven unaltered."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "record": {
+                    "type": "object",
+                    "description": "Any JSON object describing the action (tool, args, "
+                                   "result, actor, etc.). A `ts` timestamp is added if absent.",
+                    "additionalProperties": True,
+                },
+            },
+            "required": ["record"],
+        },
+    },
+    {
+        "name": "ledger_verify",
+        "description": ("Verify the hash chain over the whole log. Returns ok + row "
+                        "counts, and names the exact line of the first break if the log "
+                        "was edited, had a row deleted, or was reordered."),
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+]
+
+
+def _result(id_, payload):
+    return {"jsonrpc": "2.0", "id": id_, "result": payload}
+
+
+def _error(id_, code, message):
+    return {"jsonrpc": "2.0", "id": id_, "error": {"code": code, "message": message}}
+
+
+def _text_content(obj) -> dict:
+    return {"content": [{"type": "text", "text": json.dumps(obj)}]}
+
+
+def handle(msg: dict, log: Ledger):
+    """Return a response dict, or None for notifications (no id)."""
+    mid = msg.get("id")
+    method = msg.get("method")
+    if mid is None:  # notification (e.g. notifications/initialized) — no reply
+        return None
+
+    if method == "initialize":
+        return _result(mid, {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "ledger", "version": "0.1.0"},
+        })
+    if method == "tools/list":
+        return _result(mid, {"tools": TOOLS})
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        try:
+            if name == "ledger_append":
+                record = args.get("record")
+                if not isinstance(record, dict):
+                    return _result(mid, {**_text_content(
+                        {"error": "record must be a JSON object"}), "isError": True})
+                chain = log.append(record)
+                return _result(mid, _text_content({"ok": True, "chain": chain}))
+            if name == "ledger_verify":
+                r = log.verify()
+                return _result(mid, _text_content(r.__dict__))
+            return _result(mid, {**_text_content(
+                {"error": f"unknown tool {name}"}), "isError": True})
+        except Exception as e:  # never crash the server on one bad call
+            return _result(mid, {**_text_content({"error": str(e)}), "isError": True})
+
+    return _error(mid, -32601, f"method not found: {method}")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--log", default="agent.log.jsonl", help="ledger file path")
+    args = ap.parse_args(argv)
+    log = Ledger(args.log)
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except ValueError:
+            continue  # not JSON-RPC; skip
+        resp = handle(msg, log)
+        if resp is not None:
+            sys.stdout.write(json.dumps(resp) + "\n")
+            sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

arcaeon_ledger-0.2.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "arcaeon-ledger"
+version = "0.2.0"
+description = "Tamper-evident, hash-chained action log for AI agents. Prove what your agent did."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Arcaeon" }]
+keywords = ["ai", "agents", "mcp", "audit", "tamper-evident", "provenance", "hash-chain"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.scripts]
+ledger = "ledger.cli:main"
+
+[project.urls]
+Homepage = "https://arcaeon.io"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ledger"]

arcaeon_ledger-0.2.0/test_ledger.py

@@ -0,0 +1,97 @@
+"""Tests for ledger — the whole product claim is 'tamper-evident,' so the
+negative test (tampering is CAUGHT at the exact line) is the load-bearing one.
+Run: python test_ledger.py
+"""
+import json
+import tempfile
+from pathlib import Path
+
+from ledger import Ledger
+
+
+def test_append_and_verify_clean():
+    with tempfile.TemporaryDirectory() as d:
+        log = Ledger(Path(d) / "a.jsonl")
+        for i in range(5):
+            log.append({"tool": "search", "n": i})
+        r = log.verify()
+        assert r.ok, r
+        assert r.rows == 5 and r.chained == 5 and r.prechain == 0
+    print("PASS clean append+verify (5 rows chain intact)")
+
+
+def test_tamper_edit_is_caught():
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "b.jsonl"
+        log = Ledger(p)
+        for i in range(5):
+            log.append({"tool": "pay", "amount": i})
+        # Tamper: edit row 3's amount in place, keep its (now-wrong) chain.
+        lines = p.read_text(encoding="utf-8").splitlines()
+        obj = json.loads(lines[2])
+        obj["amount"] = 999
+        lines[2] = json.dumps(obj, ensure_ascii=False)
+        p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        r = log.verify()
+        assert not r.ok, "tamper went undetected!"
+        assert r.first_break == "line 3: chain mismatch", r.first_break
+    print(f"PASS tamper caught at exact line (first_break='line 3: chain mismatch')")
+
+
+def test_delete_row_is_caught():
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "c.jsonl"
+        log = Ledger(p)
+        for i in range(5):
+            log.append({"event": i})
+        lines = p.read_text(encoding="utf-8").splitlines()
+        del lines[2]  # delete row 3
+        p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        r = log.verify()
+        assert not r.ok, "deletion went undetected!"
+    print("PASS deletion caught (removing a row breaks the chain)")
+
+
+def test_reorder_is_caught():
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "e.jsonl"
+        log = Ledger(p)
+        for i in range(5):
+            log.append({"event": i})
+        lines = p.read_text(encoding="utf-8").splitlines()
+        lines[1], lines[3] = lines[3], lines[1]  # swap rows 2 and 4
+        p.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        r = log.verify()
+        assert not r.ok, "reorder went undetected!"
+    print("PASS reorder caught (swapping rows breaks the chain)")
+
+
+def test_authority_block_is_chained():
+    from ledger import authority
+    with tempfile.TemporaryDirectory() as d:
+        p = Path(d) / "auth.jsonl"
+        log = Ledger(p)
+        auth = authority("agent://scout-7", capability_version="v3",
+                         tool_schema={"name": "web.search", "args": ["q"]},
+                         time_source="ntp")
+        log.append({"tool": "web.search", "q": "weather"}, authority=auth)
+        # the authority block is present, hashed schema, and inside the chain
+        row = json.loads(p.read_text(encoding="utf-8").splitlines()[0])
+        assert row["authority"]["principal"] == "agent://scout-7"
+        assert row["authority"]["capability_version"] == "v3"
+        assert len(row["authority"]["tool_schema_hash"]) == 16
+        assert log.verify().ok
+        # tamper the principal -> chain must break (authority is protected)
+        row["authority"]["principal"] = "agent://impostor"
+        p.write_text(json.dumps(row) + "\n", encoding="utf-8")
+        assert not log.verify().ok, "editing the authority block should break the chain!"
+    print("PASS authority block chained + tamper-protected")
+
+
+if __name__ == "__main__":
+    test_append_and_verify_clean()
+    test_tamper_edit_is_caught()
+    test_delete_row_is_caught()
+    test_reorder_is_caught()
+    test_authority_block_is_chained()
+    print("\nALL PASS — tamper-evidence holds against edit, delete, and reorder.")