canon-gate 0.5.5

Reference implementation of a policy-enforced execution layer for AI and automation runtimes.

Canon Gate

Canon Gate is a reference implementation of a policy-enforced execution layer designed to sit between systems that generate structured actions (including agents, automation workflows, and other upstream runtimes) and the systems that execute them. It provides a deterministic governance layer to ensure that all actions are validated against a clear policy before they are performed.

Why does it exist?

As AI-driven and autonomous systems become more capable, the need for a "strong middle" layer to govern their actions becomes critical. Canon Gate provides this layer, ensuring that even as agentic systems become more complex, their actions remain constrained by human-defined policy. It separates the probabilistic world of AI reasoning from the deterministic world of execution.

How do I experience it? (The Golden Path)

The recommended first experience of Canon Gate is to run the flagship demonstration, which shows how an external Runtime Host uses the Runtime Protocol to have its actions governed by Canon Gate. You will observe this entire process live in the Operator Console.

This journey has three parts: an "Allowed" scenario, an "Unsatisfiable" scenario, and an "Egress Governance Denial" scenario.

Reference Demonstration

To keep Canon Gate itself incredibly lightweight and unopinionated, the demonstration separates the core governance service from the reasoning engine:

• Reasoning Engine: Gemini CLI
• Purpose: Demonstrates one possible Runtime Host implementation.
• Replaceable? Yes. Canon Gate never communicates directly with a reasoning engine. It governs the structured ActionProposal produced upstream. Any system capable of producing a valid ActionProposal may replace the reasoning engine.

Component Requirements Matrix

Component	Canon Gate	Reference Demo
Canon Gate Service	✅	✅
Operator Console	Optional	✅
Runtime Host	Optional	✅
Gemini CLI	Not Required	✅
Node.js	Not Required	✅

Note: Gemini CLI and Node.js are only required for the reference Runtime Host demonstration. Canon Gate itself is reasoning-engine agnostic and can be integrated with any system capable of producing a valid ActionProposal.

The Canon Gate CLI is a convenience interface for running the reference implementation. It is not required for integrating Canon Gate into your own applications. Most production integrations typically communicate directly with the Canon Gate HTTP API using the Runtime Protocol.

---

Step 1 — Install Dependencies

Install Canon Gate into your Python environment.

pip install canon-gate

(The reference demonstration also requires the Gemini CLI. If you do not have it, run npm install -g @google/gemini-cli).

Step 2 — Initialize Project Configuration

Navigate to (or create) the directory that will contain your Canon Gate project configuration.

Initialize the project with example policy templates:

canon-gate init

This creates the local project configuration (policy.toml and adapter_policy.toml) that Canon Gate will use for policy evaluation.

Important: Canon Gate loads project configuration (policy.toml and adapter_policy.toml) from the current working directory. Continue running the CLI commands below from this same directory unless you intentionally create another Canon Gate project.

The generated files (policy.toml and adapter_policy.toml) are configured for local project governance. The provided templates are intentionally designed to support the reference demonstration out of the box. Always review and customize these policies before deploying in production.

Step 3 — Run the Demonstration

The reference demonstration uses two terminal windows.

Terminal 1 — Canon Gate Service

From the same project directory above, start the Canon Gate server:

canon-gate serve

Leave this terminal running.

The Operator Console will automatically open in your browser.

---

Terminal 2 — Runtime Host

Open a second terminal.

Navigate to the same project directory.

If using a virtual environment, activate the same environment used to start the Canon Gate service.

For example (Windows):

.\test_env\Scripts\Activate.ps1

Then run:

canon-gate demo

💡 Note on Probabilistic Outputs

The reference Runtime Host relies on an external reasoning engine (LLM). Because LLMs are probabilistic, they may occasionally return malformed or incomplete JSON instead of a valid ActionProposal.

The Runtime Host treats this output as untrusted input. It validates the response before submitting anything to Canon Gate. If validation fails, the workflow stops and no request is sent to Runtime Enforcement.

You can observe this behavior in the Operator Console. A RuntimeSession will be recorded, but its timeline will end at the Reasoning or ActionProposal Validation stage. No Runtime Enforcement stage will be present because Canon Gate was never invoked.

This behavior is intentional and demonstrates the separation of responsibilities between the Runtime Host and Canon Gate. The Runtime Host is responsible for validating probabilistic model output before deterministic policy enforcement begins.

The Runtime Host will execute three scenarios against the running Canon Gate service:

1. Allowed Action: The host requests to write a demonstration artifact. This action is allowed by policy, and the script runs to successfully write a file to demonstration_output/canon_gate_demonstration.md on your local filesystem.
2. Unsatisfiable Objective: The host requests to delete that same artifact. The Runtime Host correctly identifies that no available capability can satisfy this objective, and it terminates gracefully before contacting Canon Gate, leaving the artifact untouched.
3. Egress Governance Denial: The host requests to run a health check in quiet mode. The reasoning engine proposes a semantically valid health check action, but because it attempts to pass an unapproved parameter (--quiet instead of the allowed --verbose), Canon Gate's Egress validation deterministically blocks execution.

After completion, inspect all three Runtime Sessions in the Operator Console.

You will see the full, three-scenario demonstration run in your terminal. When it's complete, the Operator Console (which was automatically opened) will contain the detailed RuntimeSession logs for all three scenarios, ready for your inspection.

This is the core value of Canon Gate: deterministic governance of agentic behavior.

Where do I learn more?

Now that you have seen Canon Gate in action, explore the documentation to understand its architecture, configure and extend its capabilities, or begin contributing to the project.

🧠 Learn the Architecture

These documents establish the core vocabulary, protocol interactions, runtime contracts, and design principles of the framework:

• Core Concepts: The canonical glossary defining the system's core terminology.
• Runtime Protocol: The sequential interaction flow between the Runtime Host and Canon Gate.
• Manifest: How Canon Gate exposes its policy surface for dynamic Runtime Discovery.
• Architecture: A deeper dive into the "Strong Middle" and Two-Phase Validation design.

🔌 Build with Canon Gate

These documents explain how to configure, integrate, extend, observe, and experiment with Canon Gate:

• Configuration: How to configure Ingress policies (policy.toml) and Egress policies (adapter_policy.toml).
• Integration Guide: The primary patterns for connecting Canon Gate to your own applications.
• Adapters: The guide for writing custom, schema-driven execution adapters.
• Examples: A guide to the primary ways to experience, evaluate, and test the HTTP API.
• Operator Console: The reference workspace for observing protocol execution.

🤝 Contribute

These documents explain how contributors should validate changes and participate in active development:

• Testing Guide: How to activate the virtual environment and validate changes using pytest.
• Contributing: The contribution philosophy, development workflows, and internal state guidelines.