The Kernel

Mental Model

An agent issues a tool call. The kernel intercepts that call, walks a verified capability through a pipeline of guards, and produces a verdict. If every guard agrees, the kernel forwards the call to the tool server. The tool runs and returns a response. The kernel writes a signed receipt. Nothing reaches the tool unless the pipeline allowed it; nothing reaches the agent without a receipt.

Three properties hold for every call through the kernel:

• Synchronous evaluation. The guard pipeline runs to completion before the tool is invoked. There is no probabilistic admission and no asynchronous deferral on the critical path.
• Fail-closed. Any guard that returns Verdict::Deny or anErr stops the call. See Fail-Closed Semantics.
• Receipts always. Allowed calls, denied calls, and human-pending calls all produce a signed receipt. The receipt is the audit boundary.

Glossary

These terms recur throughout the Kernel docs. The definitions here are the ones the source code uses.

The Platform Scale Ladder

Platform has six sections. The first four are a ladder of scale: one call, one process, one authority's fleet, then authority that descends past the operator. Each rung adds exactly one thing the rung below cannot express. The last two are not scale. Federation & Compliance is the standing relationship between authorities and the outside regimes it is mapped to; Formal Assurance is what is proved rather than what runs.

Two questions come before the six. Is the subject priced, settled, or metered? Then it is Economy and off the ladder. Is it one vendor's recipe for one runtime? Then it is Build. Platform documents the obligation; another area can own the crate and the walkthrough.

A Platform page then files at exactly one of the six. The filing tests below are the first cut: read the test for the section you think a page belongs to, and if it does not fire, climb. Three rules override a test that fires, and each is worked under the table. Lowest rung wins when two fire. A guard implementing the Guard trait is Kernel whatever state it reads, so rate limit files at Kernel even though its token buckets are per process. Emission semantics file at Node even though the receipt that records the same call is Kernel.

Two clauses do most of the work. Cluster and Federation both involve more than one node; under the same key is what separates them, because a cluster shares one authority keypair, one admin service token, one shared-secret peer credential, one trust domain, and a federation shares none of those. And a Chio node hosts a kernel: a deployed process that hosts no kernel is not a node, however much it looks like infrastructure.

The Kernel-to-Node boundary is already written down in the code. crates/kernel/chio-kernel-core/src/evaluate.rs names what pure evaluation excludes: revocation lookup, budget mutation, delegation-chain joins against the receipt store, DPoP nonce replay, payment authorization, tool dispatch, and receipt persistence. What that list moves off Kernel is the implementation, not the contract. Receipt persistence is a Node subject; the receipt format, the canonical JSON it hashes, and the signing backend are Kernel, and Receipts & Audit carries them on one page, contract first and the SQLite store last. Where each implementation lands is then the per-subject test's job rather than this list's. Most file at Node. Governed-transaction evaluation climbs to Swarm with chio-governance, whose escalation ladder can require a co-signature under a key the operator does not hold. Budget mutation leaves the ladder for Economy, which owns pricing, credit, metering, and settlement.

Lowest rung wins

When two tests fire, the page files at the lowest rung where its subject is fully determined. Secrets & Signing Keys is the worked case. A cluster shares one authority keypair, so key custody reads like Cluster. But the question a reader actually arrives with, where this process loads its signing key from and how that key is protected at rest, is answered by one process reading its own disk. It files at Node. Only the part that no single process can answer, which verifier bundle and revocation checkpoint the fleet agrees on, climbs to Cluster.

The guard corollary

A guard that implements the kernel Guard trait is Kernel content even when its verdict depends on state a node holds. The guard is Kernel, the store it reads is Node, and both pages open by naming the other. That settles rate limit, session-aware, memory, and approval: all four file at Kernel while the journal, the counters, and the pending-approval record are node concerns. The standing evidence is spec/GUARDS.md section 9, where the guard logic ships in chio-guards and the SessionJournal ships in chio-http-session and is operator-wired.

The corollary reaches state a node holds. It does not reach a call to another party's service. External Guard Adapters files at Node because its subject is the out-of-process call and the per-process cache, retry budget, and circuit breaker wrapped around it. Two nodes do not share a breaker, so the Kernel test fails on the first clause.

Emission semantics are documented at Node

The tracing macros, the guard join key, and the guard metric names are documented at Node Observability. There is no Kernel observability page, by design. One call's evidence is its receipt, which is Kernel. What a process emits about itself while it runs is Node, and two nodes emit two streams.

The href prefix carries no rung

The URL prefix says nothing about which section a page files under. This page is /docs/guard-platform/overview and files at Kernel; chio.yaml Configuration is /docs/guard-platform/config and files at Node. /docs/deployment/ pages file at Node, at Cluster, and in Build under Cloud Platforms. Authors file by the filing test, never by the URL.

The same six tests applied to source directories, plus seven placements the directory path gets wrong, are on Crate Map.

Guard Categories

Every guard falls into one of five categories, distinguished by the state it reads and the phase it runs in. This is the vocabulary the rest of the Kernel docs use. The protection-area tour below groups the same catalog differently.

Capability Tour

The table groups guards by the area they protect. State read is what the guard consults beyond the request, finer-grained than the State column above. Rung is where the page files on the ladder. Every row but one is Kernel, because a guard implementing the Guard trait is Kernel content whatever state it reads.

The three guard groups in the sidebar, System Access, Session & Approval, and Content & Data, are a coarsening of this tour for navigation, not a fourth taxonomy.

How Policy Fits In

A guard implementation performs enforcement. A policy supplies its configuration. Operators write a HushSpec YAML file, the policy compiler converts it into a configured pipeline, and the kernel runs that pipeline against every request. The same guard binary serves every deployment; the policy file is what differs.

• HushSpec authoring lives in HushSpec and Write a Policy.
• Runtime configuration knobs (caches, breakers, rate limits) live in Configuration.

Trust Boundary

The kernel is the trusted component and the agent is untrusted. The tool server is neither. The threat model draws one boundary, the agent-kernel-tool trust boundary, and counts tool_execution_confinement among the 7 assets that boundary protects, so a tool server is an effect surface the kernel confines rather than a party the kernel relies on. The confinement itself is registered as an assumption, ASSUME-SUBPROCESS-ISOLATION: Tool-server subprocess isolation and OS process boundaries are assumed for effects outside the pure kernel decision core.

A native guard runs inside the kernel process, so the agent cannot reach its evaluation. A WASM guard runs in that same process, but the code it runs is the guest's, and Wasmtime is what holds the guest inside its sandbox. That containment is registered as ASSUME-WASM-ENGINE: Wasmtime is assumed to enforce its documented i32 return, trap, fuel-metering, memory-limiter, and in-process sandbox semantics for untrusted guest code. A WASM guard therefore inherits the engine's confinement, not the process trust a native guard has.

The receipt signature binds the verdict to the kernel's signing key, which is verifiable offline.

Where to Go Next

• Crate Map · which rung owns which crate, and where the directory path lies
• The Guard Trait · the contract every guard implements
• Pipelines & Composition · how guards combine into a pipeline
• Fail-Closed Semantics · what happens when something goes wrong
• Default Pipeline · what runs out of the box
• In-Process Library · the first page of Node, the next rung up