aileron: Instructions file for Claude Code

CLAUDE.md - Aileron

Aileron is a tamper-evident flight recorder for AI agents: a hash-chained journal of every tool call, Ed25519-signed checkpoints, policy enforcement before execution, and offline verification. Apache-2.0, pure Python ≥3.10, two runtime dependencies (pyyaml, cryptography).

This is a security tool that is published on PyPI. Changes here are changes to something people rely on to tell them what their agents did. Bias toward correctness and honesty over speed.

The four invariants

Break any of these and the product is no longer what it claims to be.

1. Canonical JSON is the hash input. events.canonical_json() is the single serializer the chain and signatures depend on - sorted keys, tight separators, ensure_ascii=True, allow_nan=False. Never hand-format event JSON, and never add a second copy of this function. Changing it changes every hash and invalidates existing journals.
2. capture_content gates persistence, not enforcement. Policy rules and the anomaly detector always see the full call in memory; ChainLog.append strips content from the copy it writes. Rules must fire in the default digest-only mode.
3. A prefilter may only ever skip work, never a detection. prefilter.py lets the policy engine skip a rule's regex when the payload provably cannot match it. Wrongly skipping is a rule that silently stops firing and a journal that looks clean, so everything there is deliberately lopsided: anything not understood returns None, meaning "run the regex". fold() is proven sound over every Unicode codepoint by a test, because str.lower() and str.casefold() are both quietly wrong against re.IGNORECASE. Set AILERON_NO_PREFILTER=1 to rule it out during an investigation.
4. A checkpoint signs a prefix. Appending after signing stays valid; truncating or rewriting the signed prefix does not. Checkpoints are chained to each other (index, prev_checkpoint_hash).