# Diagrams — DD-16: ZeroClaw — The Rust Microkernel Harness **Deep-Dive**: DD-16 — ZeroClaw **Diagram count**: 5 **Tool**: Mermaid (primary). Each diagram validated in [Mermaid Live Editor](https://mermaid.live). --- ## Diagram 1 — The Trait-Driven Kernel (ADR-002) **Type**: Layered architecture with trait boundary **Purpose**: The single orientation diagram. Shows the load-bearing architectural decision: the kernel depends ONLY on `zeroclaw-api` traits — never on concrete implementations. Implementations live behind feature flags and are wired through factories. This is the cleanest separation of concerns in the roster. **Reading the diagram**: Top = the kernel (runtime + config + the public trait ABI). Bottom = concrete implementations behind feature flags. The arrow is one-way: the kernel imports the traits, never the impls. Adding a provider/channel/tool is a trait impl, not a core patch. ```mermaid flowchart TB subgraph KERNEL["KERNEL — zeroclaw-runtime + zeroclaw-config + zeroclaw-api"] direction LR RT["zeroclaw-runtime
loop + policy + SOP + cron"] CFG["zeroclaw-config
TOML + secrets + autonomy"] API["zeroclaw-api
the trait ABI"] end subgraph TRAITS["THE KERNEL ABI — public traits"] direction LR MP["ModelProvider"] CH["Channel"] TL["Tool"] MEM["Memory"] OBS["Observer"] RA["RuntimeAdapter"] PER["Peripheral"] end subgraph IMPLS["IMPLEMENTATIONS — behind feature flags"] direction LR PROV["25+ Provider impls
anthropic, openai, ollama,
bedrock, gemini, glm,
compatible.rs shim"] CHANS["30+ Channel impls
Telegram, Discord, Slack,
Webhook, REST, WS"] TOOLS["12-15 Tool impls
browser, HTTP, hardware"] STORE["SQLite / Postgres / Qdrant"] end KERNEL --> TRAITS TRAITS -->|trait impls via factory| IMPLS PRINCIPLE["ADR-002: the kernel depends only on traits.
Adding anything is a trait impl, not a core patch.
This is what makes 25+ provider slots possible without bloat."] IMPLS --> PRINCIPLE style KERNEL fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8 style TRAITS fill:#14141f,stroke:rgba(94,234,212,0.6),color:#e4e4e8 style IMPLS fill:#14141f,stroke:rgba(240,168,104,0.5),color:#e4e4e8 style RT fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style CFG fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style API fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style MP fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style CH fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style TL fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style MEM fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style OBS fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style RA fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style PER fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style PROV fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style CHANS fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style TOOLS fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style STORE fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style PRINCIPLE fill:#08080c,stroke:#5eead4,stroke-width:1.5px,color:#5eead4 ``` --- ## Diagram 2 — The 6-Layer Safety Cascade **Type**: Sequential defense-in-depth cascade **Purpose**: ZeroClaw's most engineered aspect — the deepest safety surface in the thin-harness category. Shows the six independent layers as a cascade, not a toggle. Each layer blocks a different attack class. The model never bypasses layer 4 (shell policy runs before exec) or layer 6 (receipts are computed by the harness, not the model). **Reading the diagram**: Top to bottom = outer to inner. Each layer is independently defeatable, but the default ships all six on. This is Module 6's risk-tiering principle taken to its logical conclusion. ```mermaid flowchart TB L1["1. CHANNEL PAIRING / ACCESS CONTROL
allowed_users, allowed_chats,
webhook IP allowlists
enforced at the channel adapter
BEFORE the runtime sees the event"] L2["2. AUTONOMY LEVEL
readonly / supervised (default) / full
Tools risk-classified:
low runs, medium asks operator, high blocks"] L3["3. WORKSPACE BOUNDARY + PATH RULES
workspace_only confines reads/writes
forbidden_paths blocks /etc, /sys, ~/.ssh"] L4["4. SHELL COMMAND POLICY
allowed_commands (strict allowlist)
forbidden_commands
pattern-matcher runs BEFORE the shell"] L5["5. OS-LEVEL SANDBOX
auto-detected: Landlock/Bubblewrap/Firejail/Docker
Seatbelt (macOS), AppContainer (Windows)"] L6["6. TOOL RECEIPTS
HMAC-SHA256 over successful tool calls + results
fed back into conversation
detects fabricated-tool-claim attacks (Module 11)"] L1 --> L2 --> L3 --> L4 --> L5 --> L6 ANNOTATION["Each layer blocks a different attack class.
Layer 4 runs before exec (model cannot bypass).
Layer 6 is computed by the harness (model cannot forge).
The default ships all six on."] L6 --> ANNOTATION style L1 fill:#08080c,stroke:rgba(94,234,212,0.4),color:#5eead4 style L2 fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style L3 fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style L4 fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style L5 fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style L6 fill:#08080c,stroke:rgba(240,128,128,0.4),color:#f08080 style ANNOTATION fill:#08080c,stroke:#5eead4,stroke-width:1.5px,color:#5eead4 ``` --- ## Diagram 3 — Where Security Runs in the Agent Loop **Type**: Linear pipeline with a security gate between model emit and tool exec **Purpose**: Shows the load-bearing placement decision. Security does not run as a pre-filter on input or a post-hoc audit — it runs BETWEEN the model emitting a tool call and the tool executing. A block surfaces as `ToolResult::Err` the model can react to. It is not a silent failure. **Reading the diagram**: Left to right = one turn of the agent loop. The security gate is the explicit node between `model emits tool_call` and `tool invokes`. This placement is the entire reason the 6-layer cascade can intercept every model-emitted action. ```mermaid flowchart LR A["Channel delivers
message"] B["Runtime.
deliver_message"] C["Provider.chat
(any of 25+ traits)"] D["Model emits
tool_call"] E["Security.validate
6 LAYERS"] F["Tool.invoke"] G["Result back
to Provider"] H["Reply to Channel"] A --> B --> C --> D --> E E -->|allowed| F --> G --> H E -->|blocked| BLOCK["ToolResult::Err
model sees the error
and can react
NOT a silent failure"] PRINCIPLE["Security runs BETWEEN model emit and tool exec.
This is the correct layer: a block surfaces as
ToolResult::Err the model can react to.
The model cannot bypass layer 4 (runs before exec)
or layer 6 (receipts are harness-computed)."] H --> PRINCIPLE BLOCK --> PRINCIPLE style A fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style B fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style C fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style D fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style E fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style F fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style G fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style H fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style BLOCK fill:#08080c,stroke:rgba(240,128,128,0.4),color:#f08080 style PRINCIPLE fill:#08080c,stroke:#5eead4,stroke-width:1.5px,color:#5eead4 ``` --- ## Diagram 4 — The Thickness Paradox (philosophy vs implementation) **Type**: Two-column comparison with a gap **Purpose**: The honesty diagram. Resolves the misconception that "thin harness means small codebase." ZeroClaw is uncompromisingly thin by PHILOSOPHY but medium-thick by IMPLEMENTATION. The gap between them is what RFC #5574 (microkernel refactor) is closing. **Reading the diagram**: Left = the thin philosophy (what the operator experiences: single binary, no telemetry, no SaaS, no hidden prompts). Right = the implementation reality (~700-800k Rust LOC, 1015 files, hardware/GPIO/SPI/USB support). The annotation names the gap and the refactor closing it. ```mermaid flowchart TB subgraph PHIL["THIN BY PHILOSOPHY — what the operator experiences"] P1["Single binary
no telemetry, no SaaS,
no license server"] P2["No hidden system prompts
'the model sees what you configure'"] P3["Operator-owned
responsibility for prompt behavior
on the operator"] P4["Self-hostable
no vendor dependency"] end subgraph IMPL["MEDIUM-THICK BY IMPLEMENTATION — the as-built artifact"] I1["~700-800k Rust LOC
across 1,015 files"] I2["~26 MiB binary
config schema alone 1.3 MB"] I3["25+ provider slots
30+ channel impls"] I4["Hardware support
GPIO / I2C / SPI / USB
most thin harnesses don't carry"] end GAP["THE GAP = RFC #5574 (microkernel refactor).
Foundation reportedly builds with --no-default-features.
Shrinks zeroclaw-runtime so kernel = loop + policy,
everything else behind feature flags.
Honest framing: thin by design, medium by implementation,
in-flight refactor to re-thin."] PHIL --> GAP IMPL --> GAP style PHIL fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8 style IMPL fill:#14141f,stroke:rgba(240,168,104,0.5),color:#e4e4e8 style P1 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style P2 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style P3 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style P4 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style I1 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style I2 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style I3 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style I4 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style GAP fill:#08080c,stroke:#f0a868,stroke-width:1.5px,color:#f0a868 ``` --- ## Diagram 5 — Explicit-Only Memory vs Model-Initiated Free Writes (ZeroClaw vs Hermes) **Type**: Two-track comparison **Purpose**: The security-property diagram. Shows why ZeroClaw's "explicit-only memory" is a deliberate security choice, not a missing feature. Compares ZeroClaw's design against Hermes's model-initiated-free-writes (DD-08). The trade is capability vs. security: an indirect injection cannot silently persist itself under ZeroClaw's design. **Reading the diagram**: Top = ZeroClaw (memory_store must be called explicitly; an injection cannot persist itself silently). Bottom = Hermes (model-initiated free writes; compounding capability but larger poisoning surface). The annotation names the trade as intentional, not a deficiency. ```mermaid flowchart LR subgraph ZC["ZEROCLAW — explicit-only memory"] direction TB Z1["Prompt context, tool output,
files, and logs are NOT
durable memory by default"] Z2["A turn becomes memory ONLY
if the agent calls memory_store
EXPLICITLY"] Z3["SECURITY PROPERTY:
an indirect injection cannot
silently persist itself"] Z1 --> Z2 --> Z3 end subgraph HER["HERMES (DD-08) — model-initiated free writes"] direction TB H1["The agent writes to memory
freely across turns"] H2["Enables compounding capability
(self-evolving skills)"] H3["TRADEOFF:
larger poisoning surface"] H1 --> H2 --> H3 end TRADE["THE TRADE = capability vs. security.
ZeroClaw trades compounding capability
for a smaller poisoning surface.
Both are defensible; the choice depends
on whether the deployment values
compounding or hardening more."] ZC --> TRADE HER --> TRADE style ZC fill:#14141f,stroke:rgba(94,234,212,0.5),color:#e4e4e8 style HER fill:#14141f,stroke:rgba(240,168,104,0.5),color:#e4e4e8 style Z1 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style Z2 fill:#08080c,stroke:rgba(94,234,212,0.3),color:#5eead4 style Z3 fill:#08080c,stroke:rgba(94,234,212,0.4),color:#5eead4 style H1 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style H2 fill:#08080c,stroke:rgba(240,168,104,0.3),color:#f0a868 style H3 fill:#08080c,stroke:rgba(240,168,104,0.4),color:#f0a868 style TRADE fill:#08080c,stroke:#5eead4,stroke-width:1.5px,color:#5eead4 ``` --- ## Validation notes - All five diagrams use the course design system colors: `#14141f` panel fill, `#08080c` deep background for nested nodes, `#5eead4` teal accent for input/state surfaces and principle nodes, `#f0a868` warn for the permission/tool structural surfaces, `#f08080` danger for the output/resource surfaces. `#e4e4e8` / `#9494a0` for text. - Paste each into [Mermaid Live Editor](https://mermaid.live) to render. All use stable Mermaid syntax (`flowchart TB/LR`, `subgraph`, `direction LR/TB`) supported in current Mermaid (v10.4+). - For the slide deck (artifact 03), these are rendered as static captures from Mermaid Live, inlined into reveal.js. - The teal/warn/danger color coding is consistent across diagrams: teal = the input/state semantic surface and the principle/thesis nodes; warn (orange) = the permission/tool/structural surface and the gap/transitions; danger (red) = the output/resource surface and the failure/block nodes. This mapping is load-bearing — it lets the reader track which boundary a node belongs to across all five diagrams.