Architecture

Why Three Planes?

Most AI agent frameworks treat code generation as a single pipeline: prompt in, code out, hope for the best. KRAIT rejects that model. Instead, it separates concerns into three concentric planes, each with distinct mutability guarantees. The outer plane is free to change on every request. The middle plane orchestrates controlled evolution. The inner plane never changes at runtime, providing the security bedrock that makes self-modification safe.

This separation is not just architectural tidiness. It is the mechanism that allows an AI agent to rewrite parts of itself without compromising the invariants that keep it trustworthy.

The Three Planes

Mutable Periphery (Control Plane). The Gateway, Brain, and Memory subsystems handle inbound requests, LLM-driven reasoning, and state management. These components are designed to be flexible and are the parts of the system that change most frequently during normal operation.

Evolution Pipeline (Analysis Plane). When the Brain proposes new code, the proposal enters a structured pipeline: AST analysis by the Narsil NIF, test generation and execution, and finally a GitHub pull request for human review. This plane transforms intent into validated, reviewable changes.

Immutable Core (Sandbox Plane). The security analyzer, KRAIT rule engine, and FLAME-managed Docker sandboxes form the foundation. These components are compiled once and locked. No evolution proposal can modify the rules that govern evolution itself.

Design Principles

KRAIT's architecture follows three core principles drawn from both the Erlang/OTP tradition and secure systems design:

• Let it crash, but never let it escape. OTP supervisors handle process failures gracefully. The sandbox plane ensures that even catastrophic failures in generated code cannot affect the host system.
• Validate at the AST, not the string. Security rules operate on parsed abstract syntax trees through Rust NIFs, not on raw text. Pattern-matching on structure is more reliable than pattern-matching on strings.
• Humans approve, machines enforce. Every evolution requires a human-approved merge. The system enforces constraints automatically, but the final gate is always a person.