Architecture

Chio is a Cargo workspace under crates/. The Guard Platform is roughly five groups of crates: core types, kernel variants, guards, policy, and protocol adapters, with storage and config underneath. This page is the map.

Core & Types

Every other crate depends on these.

Crate	Purpose
`chio-core-types`	Pure type definitions: capability tokens, scopes, receipts, governed-transaction shapes. `no_std`-portable.
`chio-core`	Crypto primitives, capability signing/verification, receipt signing. The standard-library, host-side counterpart to `chio-core-types`.

Kernel Variants

There is one Chio kernel; it ships in four crates because the same evaluation has to run in environments with different 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). Same JSON-in/JSON-out posture. UDL file in `src/chio_kernel_mobile.udl`.

Why two kernels exist

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 full kernel. That split is what lets the same verdict-producing code run in a browser tab and in a production sidecar with zero divergence.

Guards

Concrete 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. Today this is `SqlQueryGuard` with operation/table/column/predicate allowlists. Designed to grow vector DB and warehouse-cost guards in the same surface.
`chio-external-guards`	Concrete 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.1.0 WIT). Backed by wasmtime, with fuel limits and per-call deadlines.
`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`	Procedural macros that generate the WIT export glue for guards authored against the SDK.
`chio-guard-registry`	OCI distribution surface for `.arcguard` WASM-component artifacts. Pull, publish, cache, offline bundle. Sigstore verification delegated to `chio-attest-verify`.

Policy

chio-policy owns the HushSpec policy format: YAML schema types, the evaluate function, and the merge/inheritance rules. Compiled policies feed the guard pipeline configurator in chio-cli.

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 fabric.
`chio-envoy-ext-authz`	Envoy ext-authz integration for sidecar deployments.
`chio-bedrock-converse-adapter`, `chio-anthropic-tools-adapter`, `chio-openai`	Provider-specific tool-use adapters.
`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 tool surface 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…

High-level crate dependency graph. Adapters and the full kernel sit on top; the portable core is at the bottom.

Reading this graph

The portable core is at the bottom because every other layer can reuse it. Concrete guard catalog crates depend on the full kernel because they want session journals, the post-invocation pipeline machinery, and tracing. External providers depend on the catalog because they reuse the AsyncGuardAdapter infrastructure that lives there.

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/chio-kernel-core/src/lib.rs              # Verdict enum
crates/chio-kernel-core/src/guard.rs            # Guard trait, GuardContext
crates/chio-kernel-core/src/evaluate.rs         # Core evaluate() pipeline
crates/chio-kernel/src/runtime.rs               # ToolCallRequest, ToolCallResponse
crates/chio-kernel/src/kernel/mod.rs            # KernelError enum
crates/chio-guards/src/pipeline.rs              # GuardPipeline + default_pipeline
crates/chio-guards/src/advisory.rs              # AdvisoryPipeline + PromotionPolicy
crates/chio-guards/src/post_invocation.rs       # PostInvocationPipeline + SanitizerHook
crates/chio-guards/src/external/mod.rs          # AsyncGuardAdapter, ExternalGuard
crates/chio-external-guards/src/                # Concrete provider adapters
crates/chio-cli/src/policy.rs                   # Policy compiler tests

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