Canon 🏛️

Deterministic governance knowledge integrity engine for AI systems.

Canon is a lightweight, tamper-evident governance synchronization engine designed to fetch, verify, diff, and audit external regulatory and organizational policies. It acts as the structured source-of-truth pipeline for AI constitutional guardrails.

Key Features

• Source Adapters: Extensible adapters for crawling structured authorities (e.g., OWASP LLM Top 10, NIST AI Risk Management Framework, FINOS AI Governance).
• Deterministic State Hashing: Cryptographically hashes governance rulesets to detect changes instantly and reliably.
• Evidence Packages: Generates comprehensive diff packages detailing added, modified, deprecated, or removed rules, including severity deltas.
• Tamper-Evident Ledger: Logs all transitions to an append-only, hash-chained ledger (ledger.jsonl) to ensure auditability.
• Human-in-the-Loop Approvals: Approval gate that secures state transitions behind individually-attributed cryptographic approval records.
• Microsecond Latency: Built for high-frequency runtime checks with execution overhead under a millisecond.

Installation & Setup

1. Activate your environment and install dependencies:

   conda activate canon
   pip install -e .
   

2. Configure your GitHub token (optional, but recommended to avoid rate limits):

   set GITHUB_TOKEN=ghp_your_token_here
   

CLI Usage

1. Fetch Latest Policies

Fetch state from all tracked governance sources, compute hashes, and compare them against local baselines.

canon fetch

2. Review Pending Decisions

Interactively inspect and approve/reject/defer pending evidence packages. Each decision is written to .canon/approvals/ and appended to the ledger. Deferred packages stay in the pending queue; approved and rejected ones leave it.

canon review

3. Verify Ledger Integrity

Verify the ledger's hash chain, every approval record's hash, and that approval records and ledger approval entries match one another. Exits non-zero on any violation.

canon verify

4. Check Governance Status

Display the active version, rule count, last fetch time, and state hashes of all tracked sources.

canon status

Empirical Performance (ICAIF Benchmarks)

Under benchmark conditions (compiled on Python 3.14), Canon operates at microsecond scales, presenting negligible overhead for enterprise deployment.

Next Steps & Integrations

For a deep dive into how Canon integrates with the broader ecosystem, please read the Architecture Document.