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.

Every claim above is machine-verified

The claims: machine-verified badge links to a CI gate (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 runs in the gate, not just behind a badge link.
• Runs without Permit, Cloud, or Scan — tests/test_independence.py, plus a source scan proving the kernel never imports Cloud or Permit, plus 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.
• 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 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 the independent repositories that together close the execution gap — the gap between upstream authorization and the execution edge that actually performs a consequential side effect.

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 — a managed control plane (source-available; see its LICENSE). Not required by any component above; every capability in this ecosystem works without it.

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.

Guarantee precondition: the edge guarantee holds when the protected edge is the only path to the resource, the backend accepts only brokered credentials issued after verification, and the agent has no standing credential or alternate route. If those conditions are not met, the Kernel still refuses invalid proofs — but it cannot prevent a caller that bypasses it from reaching the resource. Full scope in docs/SCOPE_AND_GUARANTEES.md.

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.

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.

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 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.

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 and the BoundaryVerifier 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-protocol.

What the Kernel produces

Artefact	Purpose	Spec
Action Intent	The public, typed, attributable request for a consequential action	spec/action-intent/SPEC.md
PCCB	The proof artifact a protected endpoint verifies before side effects	spec/pccb/SPEC.md
Receipt	The canonical structured success outcome	spec/receipt/SPEC.md
Refusal	The canonical structured blocked-execution outcome	spec/refusal/SPEC.md
Outcome Attestation	Optional Ed25519-signed envelope wrapping a Receipt or Refusal (v2alpha1)	spec/outcome-attestation/SPEC.md
Receipt Counter-Signature	Optional third-party counter-sign on a Receipt	spec/countersignature/SPEC.md
Transparency Log Entry	Optional digest-based public anchor	spec/transparency-log/SPEC.md
Issuer Status	Key lifecycle record (active / retired / suspended / revoked / hard_revoked)	spec/issuer-status/SPEC.md
Approval Artefact	Structured approval record that PCCB issuance may require	spec/approval-artifact/SPEC.md
Protected Endpoint behaviour	The execution-edge contract	spec/protected-endpoint/SPEC.md
Replay behaviour	The single-use proof contract	spec/replay/SPEC.md

Signed receipts — what the agent had permission to do, what it did or tried, and how

Every execution attempt produces one of two canonical, machine-readable artefacts:

• A Receipt when the side effect executed (or was definitively refused before execution, in the refused-receipt path).
• A Refusal when the protected endpoint refused the attempt before any side effect.

Both are structured, hash-chained, and stable at the contract level. They answer, for any retrospective reviewer (engineer, auditor, regulator, insurer):

• What the agent had permission to do — the Grant's scopes.allow, scopes.deny, budget, rate, expires_at, and approval rules. The receipt cites the exact grant and proof that authorized this attempt.
• What it did or tried to do — the exact Action Intent (action name, target, tenant, subject, audience, parameters), the action-hash (SHA-256 over RFC 8785 canonical JSON), and the execution state (succeeded, failed, refused, outcome_unknown).
• How it did it — the brokered or resource-owned execution mode, the credential reference (not the secret), the adapter / endpoint that performed the side effect, the provider response or refusal code, and the receipt's own signature.

For deployments that need portable cryptographic attestation of origin, the Kernel can wrap any v1 Receipt or Refusal in an Outcome Attestation envelope (v2alpha1, opt-in). The attestation is signed with an Ed25519 key whose lifecycle (active / retired / suspended / soft-revoked / hard-revoked) is itself part of the public contract. A hard-revoked key's historical artefacts remain verifiable only if an independently verified external anchor proves the artefact digest existed before the compromise — see REVOCATION_AND_RECEIPT_DURABILITY.md.

Outcome Attestation is v2alpha1 and is excluded from the 1.0 compatibility promise. It is opt-in, alpha, and may change or be removed in any release until it reaches v2. See VERSIONING.md §1.2.

Install

Python 3.10+ for the Kernel alone. The full stack including Permit requires 3.11+.

pip install actenon-kernel            # full verifier: HMAC and Ed25519

Since 1.1.0 the base install verifies everything the ecosystem produces, including Ed25519 proofs and Outcome Attestations. (The [asymmetric] extra still resolves for backward compatibility; it installs nothing additional.)

Connect it to an agent (MCP, 60 seconds, zero install)

The Kernel ships a runnable MCP server, so a model can ask it whether an action is allowed before the action runs — and read back exactly why it was refused. Paste this into any MCP client (Claude Desktop, ChatGPT, or anything else that speaks MCP):

{
  "mcpServers": {
    "actenon": {
      "command": "uvx",
      "args": ["--from", "actenon-kernel[mcp]", "actenon-mcp", "--demo"]
    }
  }
}

uvx fetches and runs it — nothing to install first. --demo runs offline with an ephemeral key and in-memory state; it is clearly marked DEMO MODE in every tool description and must not be used in production.

Three tools: actenon_verify (is this proof good for this exact action?), actenon_gate (ALLOW or a typed refusal), actenon_receipt (the hash-chained receipt for a prior decision). Every refusal carries both the machine code and the human-readable reason.

Full walkthrough, including a real transcript of an agent being refused for widening a refund and then succeeding within scope: docs/integrations/MCP_QUICKSTART.md.

Use as a verifier (resource boundary)

from actenon.proof import PCCBVerifier, build_local_proof_signer

# For production, use a file-based or KMS-backed signer (see
# docs/PRODUCTION_INTEGRATION.md §1). The local HMAC signer below is
# development-only — it uses a public test secret.
signer = build_local_proof_signer()    # development only
verifier = PCCBVerifier(signer=signer)

# Raises ProofVerificationError on any failure; returns silently on success.
verifier.verify(intent, pccb, context)

Production key custody: the local HMAC signer above is for development only. For production, use a file-based Ed25519 key or a KMS-backed signer. See docs/PRODUCTION_INTEGRATION.md §1 for the three custody tiers and the ACTENON_ALLOW_PILOT_LOCAL_EDDSA_IN_PRODUCTION flag documentation.

Use as a boundary verifier (Boundary Kit, resource-owned mode)

from actenon.boundary import BoundaryVerifier, BoundaryVerificationRequest

verifier = BoundaryVerifier()
result = verifier.verify_boundary(BoundaryVerificationRequest(
    proof_token="v1.eyJ...",
    action_type="payment.refund",
    action_hash="abc123...",
    audience="service:payments",
))
# result.valid         → True / False
# result.refusal_code  → "PROOF_INVALID" | "REPLAY_DETECTED" | ""
# result.proof_id      → "proof_..."  (for receipt correlation)

Use as a minter + executor (brokered mode, full local proof)

python3 -m pip install -e .
python3 -m actenon.cli up
python3 -m actenon.cli doctor
python3 -m actenon.cli simulate --incident replit

Then protect a real endpoint:

python3 -m examples.refund_guard_local.server --runtime-dir artifacts/local_runtime

Multi-language SDKs

SDK	Use case	Path
Python (reference)	Full kernel: minter, verifier, executor, CLI, conformance, local proof mode	this repo
TypeScript	Verifier-edge proof checking in Node / Express / TS services	sdk/typescript/
Go	Verifier-edge proof checking in Go HTTP services	sdk/go/
Rust	Verifier-edge proof checking in systems components	sdk/rust/

Every SDK runs against the same 51 conformance vectors. See SDK_SELECTION_GUIDE.md.

Framework & platform adapters

The repo ships ranked, ready-to-run examples showing the Kernel wired into the major agent surfaces. MCP is the hero path; the rest are distribution-supporting.

#	Surface	Example	Where proof verification happens
1	MCP server tool (hero)	examples/mcp_server_protected_tool/	Inside the MCP tool implementation
2	LangChain tool	examples/langchain_protected_tool/	Inside the tool _run
3	Claude Managed Agents custom tool	examples/claude_managed_agents_protected_tool/	Inside the agent.custom_tool_use handler
4	LlamaIndex FunctionTool	examples/llamaindex_protected_tool/	Inside the wrapped function
5	CrewAI tool	examples/crewai_protected_tool/	Inside the tool _run
6	Semantic Kernel plugin	examples/semantic_kernel_protected_tool/	Inside the @kernel_function method

Additional examples (not in the ranked launch set, but production-quality):

Surface	Example
OpenAI Agents SDK	examples/openai_agents_sdk_protected_tool/
FastAPI protected route	examples/fastapi_protected_route/
Express protected route (TypeScript SDK)	examples/express_protected_route/
FastMCP financial transfer	examples/fastmcp_financial_transfer/
Refund guard (local admission → real proof)	examples/refund_guard_local/
Invoice payment guard	examples/invoice_payment_guard_local/
Clinical EHR agent	examples/protected_clinical_ehr_agent/
IAM control plane	examples/protected_iam_control_plane/
Multi-agent swarm	examples/protected_multi_agent_swarm/
Policy preflight refund	examples/protected_policy_preflight_refund/
LangChain finance agent	examples/protected_langchain_finance_agent/
Financial agent protected transfer	examples/financial_agent_protected_transfer/
Adversarial RSA policy stress test	examples/adversarial_rsa_policy_stress_test.py

Every example keeps the same boundary: the protected endpoint receives an Action Intent + PCCB + local context, verifies proof before any side effect, and returns a canonical Receipt or Refusal. No example requires a hosted control plane.

The incident library — see the gap, then see it closed

The repo ships a local simulator that lets you watch real-world incident patterns unfold, then watch the same pattern get refused at a protected endpoint. Run any of them in seconds:

actenon-kernel simulate --incident replit           # Replit-style destructive DB drift
actenon-kernel simulate --incident prod-delete      # Generic production destructive action
actenon-kernel simulate --scenario mcp-tool-proof-laundering
actenon-kernel simulate --scenario iam-escalation
actenon-kernel simulate --scenario data-export

Pattern	What it shows	Source-disciplined writeup
Replit-style database delete	A bounded dev task widens into a destructive DB change because the execution edge trusts broad tool authority instead of verifying the exact action + target.	docs/incidents/REPLIT_STYLE_DATABASE_DELETE.md
Production destructive action	The hero "No receipt, no prod delete" path.	docs/incidents/PRODUCTION_DESTRUCTIVE_ACTION.md
MCP tool proof laundering	An orchestrator forwards proof minted for one tool to a different tool; the second tool must refuse.	docs/incidents/MCP_TOOL_PROOF_LAUNDERING.md
IAM privilege escalation	An agent attempts put_user_policy / attach_role_policy without exact-action proof.	docs/incidents/IAM_PRIVILEGE_ESCALATION_PATTERN.md
Data export exfiltration	A sensitive export action attempted without audience/scoped proof.	docs/incidents/DATA_EXPORT_EXFILTRATION_PATTERN.md

These pages are source-disciplined: they use incident names as pattern language, not as factual incident reports, and they explicitly do not assert uncited facts about any named incident. They show where the execution gap appears and how a protected Actenon boundary would require preflight, proof, credential brokering, and Receipt/Refusal artefacts before side effects. Use INCIDENT_ANALYSIS_TEMPLATE.md to write your own.

Then open the local Trace Viewer to inspect the Intent Record, Action Intent, PCCB, Receipt, Refusal, replay entries, and protected-endpoint state for any simulation:

actenon-kernel up
# → http://127.0.0.1:8421