receipt-kernel

Append-only, hash-chained run ledger with invariant evaluation.

Zero dependencies. Stdlib only. Python 3.10+.

What it does

• Run ledger: append-only, hash-chained event store (SQLite, WAL mode)
• Stage machine: explicit stage graph with hard-fail on illegal transitions
• Evidence store: content-addressed blobs with pre-write redaction and retention policies
• Invariant evaluation: PASS / WARN / FAIL / UNKNOWN — no silent downgrade

What it doesn't do

No daemons, schedulers, reconciliation loops, plugins, auth, tenancy, or LLM abstractions. It records what happened, proves the chain is intact, and evaluates invariants. That's it.

Install

pip install receipt-kernel

Quick start

from receipt_kernel import Verdict
from receipt_kernel.store_sqlite import SqliteReceiptStore
from receipt_kernel.envelope import make_envelope

# Create a store
store = SqliteReceiptStore(":memory:")
store.initialize_schema()

# Start a run
run_id = "run-001"
store.ensure_run(run_id, policy_id="default", policy_version="1.0", stage_graph_id="default")

# Append an event (store fills run_id, seq, prev_hash, event_hash)
env = make_envelope(
    event_type="RUN_START",
    stage="START",
    actor_kind="system",
    actor_id="test",
    policy_id="default",
    policy_version="1.0",
    stage_graph_id="default",
    payload={"task": "example"},
)
store.append_event(run_id, env)

events = store.get_events(run_id)
print(f"Events: {len(events)}, chain intact: {events[0]['event_hash'] is not None}")

Invariants

Six constitutional invariants ship with the kernel:

All invariants return InvariantResult with a Verdict. Any UNKNOWN or FAIL in required invariants poisons overall success.

Verdicts

from receipt_kernel import Verdict

Verdict.PASS     # verified and satisfied
Verdict.WARN     # verified but degraded
Verdict.FAIL     # verified and violated
Verdict.UNKNOWN  # cannot verify (missing evidence, read failure)

UNKNOWN is a failure, not a shrug.

Evidence

Evidence is stored as content-addressed blobs (blob://sha256:<hex>).

Two evidence classes:

• public: retained longer, safe for logging
• sealed: aggressively expired, encrypted-at-rest when applicable

An optional redaction hook runs before persistence (13 built-in secret patterns).

License

Apache-2.0