Architecture · Chio Docs

Core & Types

These crates define shared types and data-only helpers.

Crate Purpose

chio-core-types The canonical protocol types and the crypto that signs them: capabilities, receipts, sessions, messages, manifests, and canonical JSON, plus the crypto module (Ed25519 signing backends, Keypair, SignedCanonicalPayload; the pq feature adds ML-DSA-65 and hybrid) and hashing/Merkle (sha256, MerkleTree, MerkleProof). no_std + alloc by source, so it cross-compiles to wasm32-unknown-unknown and other embedded targets.

chio-core Unified imports for chio-core-types and the economic and trust domain crates (appraisal, autonomy, credit, federation, governance, listing, market, open-market, underwriting, web3). Pure data and cryptography (no I/O, no runtime state), so it too compiles for WASM, embedded, and alloc-only targets. Adds three contracts of its own: the extension and official-stack model, the identity-network model, and the portable-standards catalog. Request evaluation and receipt signing live in chio-kernel, not here.

Crate	Purpose
`chio-core-types`	The canonical protocol types and the crypto that signs them: capabilities, receipts, sessions, messages, manifests, and canonical JSON, plus the `crypto` module (Ed25519 signing backends, `Keypair`, `SignedCanonicalPayload`; the `pq` feature adds ML-DSA-65 and hybrid) and hashing/Merkle (`sha256`, `MerkleTree`, `MerkleProof`). `no_std` + `alloc` by source, so it cross-compiles to `wasm32-unknown-unknown` and other embedded targets.
`chio-core`	Unified imports for `chio-core-types` and the economic and trust domain crates (appraisal, autonomy, credit, federation, governance, listing, market, open-market, underwriting, web3). Pure data and cryptography (no I/O, no runtime state), so it too compiles for WASM, embedded, and `alloc`-only targets. Adds three contracts of its own: the extension and official-stack model, the identity-network model, and the portable-standards catalog. Request evaluation and receipt signing live in `chio-kernel`, not here.

Kernel Variants

Four crates provide kernel implementations for environments with different runtime capabilities.

Crate	Purpose
`chio-kernel-core`	Pure-compute portable kernel. `#![no_std]` with `extern crate alloc;`. Runs on `wasm32-unknown-unknown` and `wasm32-wasip1`. Owns the sync `Guard` trait, `GuardContext`, `PortableToolCallRequest`, `Verdict`, and the core `evaluate()` function. Never produces `PendingApproval`.
`chio-kernel`	Full kernel for the desktop sidecar. Adds tokio tasks, the rusqlite-backed receipt and revocation stores, the price oracle, the DPoP nonce cache, async session ops, HTTP/stdio transports, and the HITL approval shell. Re-exports the core types and bridges them to its own `ToolCallRequest` with DPoP, governed-intent, and approval-token fields. This is the only kernel that emits `Verdict::PendingApproval`.
`chio-kernel-browser`	Browser bindings over the portable core. Wires `js_sys::Date::now()` into the `Clock` trait and `window.crypto.getRandomValues` into `Rng`. JSON-in/JSON-out across the wasm-bindgen boundary.
`chio-kernel-mobile`	UniFFI wrapper over the portable core for iOS (Swift) and Android (Kotlin). It uses JSON input and output. Its UDL file is `src/chio_kernel_mobile.udl`.

Portable and desktop kernel roles

The portable core does the deterministic part of evaluation: signature checks, scope match, sync guard pipeline. Anything that touches I/O, async, SQLite, or HTTP lives in the desktop kernel. Browser and mobile crates reuse the portable core; their I/O behavior is outside that shared evaluation path.

Guards

Guard implementations live in dedicated crates so they can be swapped, replaced, or omitted by deployments that do not need them.

Crate	Purpose
`chio-guards`	The main guard catalog: forbidden-path, path-allowlist, shell-command, egress-allowlist, mcp-tool, secret-leak, patch-integrity, velocity, jailbreak, response sanitization, advisory and post-invocation pipelines, plus the external adapter infrastructure.
`chio-data-guards`	Guards that inspect data-store semantics. Ships four: `SqlQueryGuard` (operation/table/column/predicate allowlists), `VectorDbGuard`, `WarehouseCostGuard`, and `QueryResultGuard`, a post-invocation hook that inspects returned rows.
`chio-external-guards`	External providers: Bedrock, Azure Content Safety, Vertex Safety, Safe Browsing, VirusTotal, Snyk. Each implements `ExternalGuard` and composes with the `AsyncGuardAdapter` from `chio-guards`. Hosts URL validation against SSRF.
`chio-wasm-guards`	Host runtime that loads operator-authored guards from WASM. Supports both raw core modules and the Component Model (chio:guard@0.2.0 WIT). Backed by wasmtime, with fuel limits, memory limits, and a module-size cap.
`chio-guard-sdk`	Guest SDK for authoring WASM guards in Rust. Targets the `chio:guard@0.2.0` WIT world. Wraps the host imports (`chio.log`, `chio.get_config`, `chio.get_time_unix_secs`, `host.fetch-blob`).
`chio-guard-sdk-macros`	The `#[chio_guard]` attribute macro. It wraps a plain `evaluate` function in the raw core-module ABI (a `#[no_mangle] extern "C" fn evaluate(ptr, len)` entry point plus the `chio_alloc`, `chio_free`, and `chio_deny_reason` exports), not Component Model WIT glue.
`chio-guard-registry`	OCI distribution for `.arcguard` WASM components. It pulls, publishes, caches, and bundles them for offline use. Signature verification is delegated to `chio-attest-verify`.

Policy

chio-policy owns the HushSpec policy format: YAML schema types, the evaluate function, and the merge/inheritance rules. Its compile_policy compiler turns a HushSpec document into a configured GuardPipeline plus PostInvocationPipeline, which chio-cli wires into the running kernel.

Protocol Adapters & Edges

Each adapter front-ends the kernel for one protocol. They translate wire requests into ToolCallRequest and the kernel's response back into the protocol's reply shape.

Crate	Purpose
`chio-mcp-adapter`, `chio-mcp-edge`	MCP wire adapter and edge process.
`chio-a2a-adapter`, `chio-a2a-edge`	A2A protocol adapter and edge.
`chio-acp-edge`, `chio-acp-proxy`	ACP protocol edge and proxy.
`chio-openapi`, `chio-openapi-mcp-bridge`	OpenAPI ingest and bridging to MCP.
`chio-tool-call-fabric`	Cross-provider tool-call routing.
`chio-envoy-ext-authz`	Envoy ext-authz integration for sidecar deployments.
`chio-anthropic-tools-adapter`, `chio-bedrock-converse-adapter`, `chio-cohere-tools-adapter`, `chio-gemini-tools-adapter`, `chio-groq-tools-adapter`, `chio-mistral-tools-adapter`, `chio-ollama-tools-adapter`, `chio-openai-adapter`	Provider-specific tool-use adapters, one per model provider.
`chio-cross-protocol`	Cross-protocol bridging logic.

Storage & Config

Crate	Purpose
`chio-config`	Loader for `chio.yaml` with environment-variable interpolation, strict `deny_unknown_fields` deserialization, and post-load validation.
`chio-manifest`	Tool-server manifest format. Declares the tools a server exposes plus its required permissions. Signed with the server's Ed25519 key, verified before admission.
`chio-store-sqlite`	rusqlite-backed receipt store, revocation list, and budget state. Used by `chio-kernel`.

Dependency Graph

High-level view of who depends on whom. Arrows point from the consumer to the provider.

rendering…

Crate dependency graph. Adapters and the desktop kernel depend on the portable core and shared types.

Reading this graph

The portable core appears at the bottom because the displayed crates reuse it. Guard catalog crates depend on the desktop kernel because they want session journals, the post-invocation pipeline implementation, and tracing. External providers depend on the catalog because they reuse the AsyncGuardAdapter infrastructure that lives there.

Where Guards Run

Guards are one step in a longer pre-dispatch sequence. The desktop kernel runs capability, budget, and lineage checks before the guard pipeline and authorizes payment only after it. The order in evaluate_tool_call_sync_with_session_roots (and its nested-flow sibling evaluate_tool_call_with_nested_flow_client) is:

text

1.  Verify capability signature
2.  Check time bounds (not-before / expiry)
3.  Check revocation status
4.  Check subject binding (agent identity matches capability subject)
5.  Resolve matching grants (scope check)
6.  DPoP verification, if a matching grant requires it
7.  Ensure the tool target is registered
8.  Record the capability lineage snapshot
9.  Check and increment budget
10. Validate the governed transaction, if applicable
11. Run guards            <-- the guard pipeline evaluates here
12. Authorize payment, if applicable
13. Dispatch to the tool server

Guards run after the budget, lineage, and DPoP checks but before payment is authorized. On a guard denial, any budget charge made in step 9 is reversed via reverse_budget_charge, and the denial response carries Verdict::Deny, the reason string, a signed denial receipt, and financial metadata for monetary denials.

Trust Boundaries

The architecture makes three trust assumptions explicit.

The kernel is trusted. Guards run inside the kernel process. The kernel signs receipts. An adversarial agent cannot tamper with a verdict or a receipt without breaking the signature.
The agent is untrusted. Every input the agent provides is treated as adversarial. The capability token authorizes a scope, not a specific request shape. Scope match runs before guards do.
Tool servers are cooperating. The tool server is registered, signed-manifest-bound, and trusted to implement what it advertises. It is not trusted to enforce policy. Policy enforcement is the kernel's job.

WASM custom guards run in a sandboxed wasmtime instance with fuel limits, so the trust boundary is preserved even when an operator ships their own guard binary into the platform.

Reading the Source

If you are looking for a specific behavior in the source, these are the file paths that come up most often.

text

crates/kernel/chio-kernel-core/src/lib.rs        # Verdict enum
crates/kernel/chio-kernel-core/src/guard.rs      # portable Guard trait, GuardContext
crates/kernel/chio-kernel-core/src/evaluate.rs   # core evaluate() pipeline
crates/kernel/chio-kernel/src/runtime.rs         # ToolCallRequest, Verdict
crates/kernel/chio-kernel/src/kernel/mod.rs      # KernelError, full-kernel Guard + GuardDecision
crates/guards/chio-guards/src/pipeline.rs        # GuardPipeline + default_pipeline
crates/guards/chio-guards/src/advisory.rs        # AdvisoryPipeline + PromotionPolicy
crates/guards/chio-guards/src/post_invocation.rs # SanitizerHook (pipeline types re-exported from chio-kernel)
crates/guards/chio-guards/src/external/mod.rs    # AsyncGuardAdapter, ExternalGuard
crates/guards/chio-external-guards/src/          # concrete provider adapters
crates/guards/chio-policy/src/compiler.rs        # HushSpec-to-pipeline compiler

Where to Go Next

The Guard Trait · the contract every guard implements
Pipelines & Composition · how guards combine
Default Pipeline · what runs out of the box
Deployment · running the kernel in production