Architecture

​

Design philosophy

1. Library-first — the Rust crate is the primary interface; surfaces (CLI, REST, RPC, MCP) are thin wrappers
2. Modular — twenty-five crates, all opt-in. Clean trait boundaries let you swap providers, stores, and dispatchers
3. No I/O in core — meerkat-core has no network or filesystem dependencies; all I/O is in satellite crates
4. Streaming-first — all LLM interactions use streaming for responsive user experiences
5. Budget-aware — built-in resource tracking for tokens, time, and tool calls
6. Machine authority — canonical state mutations flow through generated sealed mutator traits; handwritten code classifies inputs and executes effects but cannot invent parallel semantic state
7. Formal seam closure — async owner handoffs, wait barriers, and terminal classifications are under formal protocol ownership with generated helpers and obligation tracking

​

High-level architecture

​

Detailed component view

​

Crate structure

pub trait LlmClient: Send + Sync {
    fn stream(&self, request: &LlmRequest) -> Pin<Box<dyn Stream<Item = Result<LlmEvent, LlmError>> + Send>>;
    fn provider(&self) -> &'static str;
    async fn health_check(&self) -> Result<(), LlmError>;
    fn compile_schema(&self, output_schema: &OutputSchema) -> Result<CompiledSchema, SchemaError>;
}

pub enum LlmEvent {
    TextDelta { delta: String, meta: Option<Box<ProviderMeta>> },
    ReasoningDelta { delta: String },
    ReasoningComplete { text: String, meta: Option<Box<ProviderMeta>> },
    ToolCallDelta { id: String, name: Option<String>, args_delta: String },
    ToolCallComplete { id: String, name: String, args: Value, meta: Option<Box<ProviderMeta>> },
    UsageUpdate { usage: Usage },
    Done { outcome: LlmDoneOutcome },
}

​

Agent loop

​

States

​

Turn boundaries

1. Tool results are injected into the session
2. Steering messages (from parent agents) are applied
3. Any local projections or staged updates that follow canonical seam truth are applied
4. Delegated-work projections are collected and injected
5. Budget is checked
6. Session is checkpointed
7. turn_boundary hooks run before the next state transition

• TurnCompleted
• ToolResultReceived
• HookStarted / HookCompleted / HookFailed
• HookDenied
• HookRewriteApplied
• HookPatchPublished

​

Hook insertion points

• run_started
• run_completed
• run_failed
• pre_llm_request
• post_llm_response
• pre_tool_execution
• post_tool_execution
• turn_boundary

​

Hook pipeline architecture

​

Delegated work and forked branches

​

Comms transport design

​

Data flow through the agent loop

​

Machine authority (RMAT)

​

The core rule

1. The machine definition in meerkat-machine-schema — declares states, inputs, transitions, effects, and terminal outcomes
2. The generated kernel in meerkat-machine-kernels — implements a sealed mutator trait that is the sole mutation path
3. The authority wrapper in the owning crate — calls apply(input) on the kernel and executes returned effects

┌─────────────────────────────────────────────────────────────┐
│  Shell code (handwritten)                                   │
│  • classifies raw inputs → typed machine inputs             │
│  • calls authority.apply(input)                             │
│  • executes returned effects (I/O, scheduling, persistence) │
│  • CANNOT mutate canonical state directly                   │
├─────────────────────────────────────────────────────────────┤
│  Authority (handwritten wrapper)                            │
│  • holds machine state                                      │
│  • delegates to generated kernel                            │
│  • maps effects to runtime actions                          │
├─────────────────────────────────────────────────────────────┤
│  Generated kernel (sealed mutator trait)                    │
│  • ONLY code that can mutate canonical state                │
│  • typed input enum → transition → effects + new state      │
│  • compile-time seal prevents handwritten implementations   │
└─────────────────────────────────────────────────────────────┘

​

Machine catalog

​

What handwritten code may and may not do

• Classify raw inputs into typed machine inputs
• Route inputs to the correct machine owner
• Schedule and execute effects (I/O, persistence, channel management)
• Manage tokio tasks, notifiers, and completion waiters

• Mutate canonical semantic state directly
• Decide transition legality outside the machine
• Implement alternate reducers or shadow state machines
• Invent duplicate semantic enums that diverge from machine truth
• Hide transition-relevant truth in side booleans or maps the machine doesn’t own

​

RMAT audit

• Every authority module is declared in the policy
• Protected fields (wake_requested, process_requested, comms_drain_active) are only written through authority paths
• Handoff protocol coverage is complete
• Terminal mapping constraints are satisfied
• The baseline (xtask/rmat-baseline.toml) has zero open findings

​

Formal seam closure

​

The three closed seams

1. Comms drain seam: TurnExecutionMachine emits SpawnDrainTask/AbortDrainTask effects. The comms drain lifecycle must spawn or abort the actual drain task and feed back TaskSpawned/TaskExited. Generated protocol helpers (protocol_comms_drain_spawn.rs, protocol_comms_drain_abort.rs) constrain the obligation and feedback to exactly the allowed inputs.
2. Ops barrier seam: TurnExecutionMachine delegates operation tracking to OpsLifecycleMachine. The barrier-satisfaction signal (all pending barrier ops complete) flows through AsyncOpRef with typed WaitPolicy (Barrier vs Detached). The barrier_satisfied guard on ToolCallsResolved ensures the turn cannot advance until the barrier is met.
3. Terminal outcome alignment: Machine terminal outcomes (Completed, Failed, Cancelled) are the single source of truth for surfaced API results. Generated terminal classification helpers produce exhaustive matches with no default arm, so adding a new terminal outcome is a compile error until all surfaces handle it.

​

Handoff protocol anatomy

• Obligation: what must happen (correlation fields, obligation fields)
• Allowed feedback inputs: exactly which machine inputs the owner may submit
• Closure policy: AckRequired, AckOrAbort, or TerminalClosure
• Liveness annotation: fairness assumptions under which feedback eventually occurs
• Generated helpers: obligation struct, executor function, feedback submitters — all generated, all exhaustive

​

Proof model

​

Extension points

​

Security model

1. API key isolation: keys are passed explicitly, never stored in config
2. Tool sandboxing: MCP tools execute in separate server processes
3. Input validation: JSON Schema validation for tool arguments
4. Delegated-work isolation: forked branches and mob-managed child workflows do not get implicit recursive orchestration powers

​

Crate ownership

​

Dependency rules

1. meerkat-models depends on nothing in the workspace (leaf crate)
2. meerkat-machine-schema depends on nothing in the workspace (leaf crate)
3. meerkat-core depends on meerkat-models for catalog data and defaults
4. meerkat-machine-kernels depends on meerkat-machine-schema for definitions
5. All runtime crates depend on meerkat-core for types and traits
6. meerkat-tools depends on meerkat-mcp for MCP routing
7. meerkat (facade) re-exports from all crates
8. meerkat-cli is the top-level binary crate

​

See also

• RMAT - Rust Machine Authority Theory foundational document
• Formal seam closure - ADR for handoff protocol design
• Finite ownership ledger - state cell and semantic operation inventory
• Rust SDK reference - types, traits, and usage examples
• API reference - quick-lookup type index
• Session contracts - concurrency, durability, and compaction semantics
• Capability matrix - build profiles, error codes, feature behavior
• Configuration - config file reference