actenon-kernel

# Actenon Kernel

<!-- mcp-name: io.github.Actenon/kernel -->

> The open verifier for proof-bound consequential execution. Defines what a valid proof is. Verifies proofs at the execution edge; issues no grants; runs no policy decisions.

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
<!-- PYTHON-BADGE:START -->
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
<!-- PYTHON-BADGE:END -->
[![PyPI: actenon-kernel](https://img.shields.io/pypi/v/actenon-kernel?label=PyPI)](https://pypi.org/project/actenon-kernel/)
[![Conformance 1.0.0](https://img.shields.io/badge/Conformance-1.0.0--51%20vectors-success.svg)](docs/CONFORMANCE.md)
[![Spec v1](https://img.shields.io/badge/Spec-v1-stable.svg)](docs/SPEC_INDEX.md)
[![Versioning: SemVer 1.x](https://img.shields.io/badge/Versioning-SemVer%201.x-blue.svg)](VERSIONING.md)
[![SDKs: Py · TS · Go · Rust](https://img.shields.io/badge/SDKs-Py%20%C2%B7%20TS%20%C2%B7%20Go%20%C2%B7%20Rust-orange.svg)](docs/SDK_SELECTION_GUIDE.md)
[![CI](https://github.com/Actenon/actenon-kernel/actions/workflows/ci.yml/badge.svg)](https://github.com/Actenon/actenon-kernel/actions/workflows/ci.yml)
[![Invariants](https://github.com/Actenon/actenon-kernel/actions/workflows/invariants.yml/badge.svg)](https://github.com/Actenon/actenon-kernel/actions/workflows/invariants.yml)
[![claims: machine-verified](https://img.shields.io/github/actions/workflow/status/Actenon/actenon-kernel/verify-claims.yml?branch=main&label=claims%3A%20machine-verified)](https://github.com/Actenon/actenon-kernel/actions/workflows/verify-claims.yml)
[![MCP server](https://img.shields.io/badge/MCP-connectable%20server-8A2BE2.svg)](docs/integrations/MCP_QUICKSTART.md)
[![Code style: ruff](https://img.shields.io/badge/Code%20style-ruff-black.svg)](https://docs.astral.sh/ruff/)
[![No runtime cloud dependency](https://img.shields.io/badge/Runtime-no%20cloud%20calls-2ea44f.svg)](#independence)
[![Offline verification](https://img.shields.io/badge/Verify-offline%20capable-2ea44f.svg)](tests/test_neutrality.py)
[![Kernel independence](https://img.shields.io/badge/Deps-kernel%20independent-2ea44f.svg)](tests/test_independence.py)

### Every claim above is machine-verified

The `claims: machine-verified` badge links to a CI gate
([`verify-claims.yml`](.github/workflows/verify-claims.yml)) that fails on
every PR, push to `main`, and once a day if any factual claim this README
makes about the kernel stops being true:

- **Zero network calls during verification** — [`tests/test_neutrality.py`](tests/test_neutrality.py)
  runs in the gate, not just behind a badge link.
- **Runs without Permit, Cloud, or Scan** — [`tests/test_independence.py`](tests/test_independence.py),
  plus a source scan proving the kernel never imports Cloud or Permit, plus
  [`scripts/assert_dep_direction.py`](scripts/assert_dep_direction.py)
  (runtime deps are exactly `actenon-protocol`).
- **The conformance count** — "51 conformance vectors" is compared against
  what `actenon-kernel conformance run` actually executes; the vector files
  themselves are hash-locked by
  [`scripts/verify_conformance_manifest.py`](scripts/verify_conformance_manifest.py).
- **Install commands** — every `pip install` in this README is resolved
  against the live registry; the Python badge is generated, not hand-edited.
- **The ecosystem table** — rendered from the protocol's `ecosystem.yaml`,
  never hand-edited.

The [Invariants](.github/workflows/invariants.yml) workflow additionally
proves on every PR that a clean, no-extras install verifies the full
conformance surface — 33/33 tests, zero skips — including Ed25519.

If a claim drifts, the badge goes red before a human notices.

---

## The Actenon ecosystem

The Kernel is one of five independent repositories that together close the **execution gap** — the gap between *upstream authorization* and the *execution edge* that actually performs a consequential side effect.

<!-- ECOSYSTEM-TABLE:START -->
| Repository | Role | Depends on | Packages |
|---|---|---|---|
| **`actenon-protocol`** | The neutral wire contract — what every artefact looks like on the wire | — | `actenon-protocol` (PyPI) · `@actenon/protocol-types` (npm) |
| **`actenon-kernel`** ← you are here | The open verifier — defines what a valid proof is | `actenon-protocol` | `actenon-kernel` (PyPI) |
| **`actenon-permit`** | The developer on-ramp and authority broker | `actenon-kernel`, `actenon-protocol` | `actenon-permit` (PyPI) · `@actenon/sdk` (npm) |
| **`actenon-scan`** | The independent static-analysis scanner | — | `actenon-scan` (PyPI) |

**Optional:** [`actenon-cloud`](https://github.com/Actenon/actenon-cloud) — a managed control plane (source-available; see its LICENSE). Not required by any component above; every capability in this ecosystem works without it.
<!-- ECOSYSTEM-TABLE:END -->

Every repo can be adopted independently. The Kernel in particular can be wired in **at the agent framework** (LangChain tool, MCP tool, Claude Managed Agents custom tool, etc.) **or independently at the resource boundary** (FastAPI route, Express route, Go HTTP handler). Both placements are first-class.

---

## What this is

The Kernel is the **trust anchor** of the Actenon ecosystem. It is:

- **Independent** — runs without Permit, Cloud, or Scan. Zero network calls during verification.
- **The verifier at the execution edge** — the `PCCBVerifier` is pure and stateless; the `ProtectedExecutor` enforces replay, escrow, idempotency, and credential brokering at the edge before any side effect, then emits the Receipt or Refusal.
- **Conformance-locked** — 51 conformance vectors define exactly what "a valid PCCB" means, in any language.
- **Multi-language** — Python reference, plus TypeScript, Go, and Rust verifier SDKs that all conform to the same vectors.
- **Framework-agnostic** — proof verification is a function call, not a framework. The same verifier runs inside a LangChain `_run`, an MCP tool handler, an Express route, or a Go HTTP handler.

The Kernel does **one thing**: it verifies that a `PCCB` (Proof of Constrained Capability Bound) authorizes an exact `Action Intent` for this caller, this target, this audience, this scope, this time window, and this single execution attempt — and the `ProtectedExecutor` refuses the attempt (no side effect, structured Refusal emitted) if verification fails. The Kernel does **not** issue grants or make policy decisions — that's Permit's job.

## Why it exists

Modern agent stacks already answer the upstream question — *should this requester be allowed to do this kind of thing?* — with authentication, policy engines, approval workflows, and audit logs. They still leave open the question the execution edge needs to answer:

> Is the exact action about to execute still the exact action that was authorized — for this endpoint, this tenant, this subject, this target, and this time window?

That unanswered question is the **execution gap**. It is where parameter mutation between approval and execution, replay of valid-looking proof, presentation to the wrong endpoint, tenant/subject rebinding, and stale-proof reuse actually happen. The Kernel closes it.

Read the canonical problem statement in [`THE_EXECUTION_GAP.md`](docs/THE_EXECUTION_GAP.md).

## The two places you can wire it in

This is the single most important architectural decision in any Actenon adoption, and the Kernel is explicitly designed for **both** placements.

### Placement A — at the agent framework (brokered mode)

The Kernel verifier runs inside the agent's tool implementation. The agent calls a tool; the tool verifies proof; the tool executes. The agent never holds a production credential — the broker resolves it after verification.

```text
agent → framework tool (LangChain / MCP / Claude / CrewAI / ...)
          ↓ verifies PCCB locally
          ↓ brokers credential
          ↓ executes side effect
       Receipt or Refusal
```

This is the path you take when you control the agent framework and want to bind every tool call to proof. See [`INTEGRATIONS.md`](docs/INTEGRATIONS.md) for the six ranked framework paths.

### Placement B — independently at the resource boundary (resource-owned mode)

The Kernel verifier runs inside the resource itself — a FastAPI route, an Express endpoint, a Go HTTP handler, an internal service method. The resource is the protected endpoint. The agent (or any caller) must present a valid PCCB to cause a side effect, regardless of how it got there.

```text
any caller (agent / human / service / attacker)
          ↓ presents PCCB
   resource boundary (FastAPI / Express / Go / ...)
          ↓ verifies PCCB locally
          ↓ executes side effect
       Receipt or Refusal
```

This is the path you take when you cannot fully trust the agent framework, when the resource is shared by multiple callers, or when the resource team and the agent team are different organizations. See the **Boundary Kit** in [`actenon-permit`](https://github.com/Actenon/actenon-permit) and the [`BoundaryVerifier`](actenon/boundary/) API in this repo.

Both placements use the same Kernel, the same PCCB shape, the same conformance vectors, and the same Receipt/Refusal artefacts. You can mix them in one deployment.

## The 15-step verification pipeline

| Phase | Steps | What's checked |
|---|---|---|
| **A: Pre-auth** | 1–5 | Structure, protocol version, canonicalisation, key resolution, signature |
| **B: Post-auth** | 6–13 | Time validity, audience, boundary, target, action, parameter digest, authority, revocation |
| **C: Stateful** | 14–15 | Replay (deferred to executor), execution eligibility |

Pre-auth failures collapse to a single public-safe code `PROOF_INVALID`. Post-auth failures disclose the specific code (`AUDIENCE_MISMATCH`, `ACTION_MISMATCH`, `REPLAY_DETECTED`, etc.) only to trusted callers. This two-layer refusal model is part of the protocol — see [`actenon-protoco