The physical and virtual reality the Unikernel inhabits.
| Term | Definition | Stack / Constraint |
|---|---|---|
| DOKS | DigitalOcean Kubernetes Service. The underlying host provider offering the Linux Kernel 5.x+ required for SCM_RIGHTS (File Descriptor passing) and the CNI network layer. | DigitalOcean |
| Scratch Container | A container image built FROM scratch. It contains no OS, no shell (/bin/sh), and no standard libraries. It holds only the static Rust binary. | Docker, musl |
| Unikernel | The architectural pattern where the application logic and the operating system interface are compiled into a single, specialized bootable entity (PID 1). | Rust, Tokio |
| PVC | A Block Storage volume mounted at /mnt/data. This is the "Home Drive" where user files, the Vector Graph, and the SurrealDB datastore persist across pod restarts. | K8s PVC |
| Ephemeral Volume | A RAM-backed emptyDir volume mounted at /tmp. Essential infrastructure for the Internal Bus (UDS) because the scratch filesystem is read-only. | K8s emptyDir |
| GPU Node | A specialized Kubernetes node hosting the LLM inference engine (e.g., vLLM or Ollama) to generate embeddings and code completions. | NVIDIA, vLLM |
| S3 Hibernate | The graceful shutdown mechanism. On SIGTERM, the system compresses /mnt/data into a tarball and streams it to S3 object storage before the pod dies. | rust-s3, flate2 |
The Rust supervision tree and process architecture.
| Term | Definition | Stack / Constraint |
|---|---|---|
| Root Harness | The minimal runtime wrapper. Wraps the Axum server in a tokio async runtime and catches SIGTERM for graceful K8s shutdown, draining active connections before terminating. | tokio | → sys:axum-router | ⚙ infra:scratch-container |
| Registry | A thread-safe DashMap owned by the Root. It acts as the "Process Table," tracking all active Agent tasks, their heartbeats, and resource usage. | dashmap |
| Lazy Static | A compile-time singleton pattern. Ensures expensive data structures (like the Lexicon) are initialized exactly once at first access, then cached for the lifetime of the process. | lazy_static |
| Watchtower | A background task spawned by the Root. It scans the Registry for "Zombie" agents (timeout > 60s) and kills them to free resources. | Tokio Task |
| WS Receiver | The "Door". A volatile, crash-only TCP listener bound to 0.0.0.0:8080. It accepts connections and immediately passes the raw File Descriptor to the Factory via the Internal Bus. It has no parsing logic. | tokio | → net:internal-bus |
| Spawner Factory | The "Bouncer". It listens on the Internal Bus for FDs. It rehydrates them into TCP streams, parses the HTTP Upgrade headers to validate the GitHub Token, and spawns the Agent Task. | passfd, tungstenite | → net:internal-bus, sys:registry |
| Agent Worker | The "Green Thread" spawned by the Factory. It contains the logic loop (Shell + Planner) for a specific user session. It communicates directly with the User via the inherited WebSocket. | tokio | → net:nervous-system, know:worldstate |
| Axum Router | Ergonomic web framework built on Tokio and Hyper. Provides type-safe routing, extractors, and async handler composition without macros. | Axum, Hyper |
| Resource Embedding | Compile-time inclusion of static assets (TTL ontologies, CSS, HTML templates) directly into the binary using include_str! and include_bytes! macros. | include_str! |
The flow of signals and data.
| Term | Definition | Stack / Constraint |
|---|---|---|
| Internal Bus | A Unix Domain Socket (UDS) located at /tmp/factory.sock. It acts as a FIFO pipe to transfer File Descriptors from the Receiver to the Factory using SCM_RIGHTS. | UnixStream |
| FD Pass | The mechanism of moving a live TCP socket from one process/task to another without dropping the connection. Allows for "Hot Handoffs." | passfd |
| Nervous System | The persistent WebSocket connection between the User (xterm) and the Agent. It carries both InputEvents (Keystrokes) and CoordinationSignals (Locks, Heartbeats). | WebSocket |
| Coordination Signal | Typed JSON messages sent over the WebSocket to synchronize state. Examples: LockInput (Agent is typing), Interrupt (User pressed Ctrl+C), Heartbeat. | Serde JSON |
| Ghost Typing | A UI behavior where the AI streams text into the terminal input line character-by-character, allowing the user to interrupt or "feel" the AI's presence. | xterm.js |
The Brain, Data Structures, and Storage.
| Term | Definition | Stack / Constraint |
|---|---|---|
| Serde | Zero-cost serialization framework. Provides derive macros for converting Rust structs to/from JSON, YAML, MessagePack without runtime reflection. | Serde, serde_json |
| WorldState | The in-memory context of the current session. Holds the active Ontology, the file system path, and the connection to the Vector Graph. | Rust Struct |
| SurrealKV | The embedded, pure-Rust database engine. It stores the Graph (Nodes/Edges) and Vectors on the PVC without needing external C++ libraries (RocksDB). | surrealdb |
| Vector Graph | A hybrid data structure. Nodes represent Code AST chunks (Functions/Structs). Edges represent semantic relationships (Calls/Imports). Configured with an HNSW index for similarity search. | HNSW |
| OWL Ontology | Web Ontology Language document in Turtle format (.ttl). Defines Classes, Properties, and Individuals with rdfs:subClassOf hierarchies and domain/range constraints. | OWL, RDF, Turtle |
| Regex Parser | Lightweight ontology extraction using pattern matching instead of full RDF libraries. Avoids heavyweight dependencies like RocksDB while maintaining sufficient expressiveness. | regex |
| Tool Lexicon | The registry of executable capabilities (e.g., fs, git, grep). The Planner "crawls" this registry to understand what actions are available to satisfy a Goal. | HashMap |
| Linguist | A specialized Actor responsible for parsing code files into ASTs using tree-sitter or syn and converting them into Graph Nodes. | tree-sitter, nom |
| Planner | The logic engine (GOAP or LLM Chain) that introspects the Tool Lexicon and WorldState to generate a sequence of actions to achieve a Goal. | LLM |
Pure Rust built-in shell with common Linux commands.
| Term | Definition | Stack / Constraint |
|---|---|---|
| ls | Lists the contents of a directory. | std::fs |
| pwd | Prints the current working directory. | std::env |
| cd | Changes the current directory. | std::fs |
| mkdir | Creates new directories. | std::fs |
| rmdir | Removes empty directories. | std::fs |
| rm | Removes files or directories. | fs_extra |
| cp | Copies files and directories. | fs_extra |
| mv | Moves or renames files and directories. | fs_extra |
| touch | Creates empty files or updates file timestamps. | std::fs |
| cat | Displays the entire content of a file. | std::fs |
| less | Displays file content page by page, allowing scrolling. | std::fs |
| head | Displays the beginning lines of a file. | std::fs |
| tail | Displays the ending lines of a file. | std::fs |
| grep | Searches for patterns within files. | regex |
| man | Displays the manual page for a given command. | Built-in |
| uname | Prints system information. | Built-in |
| whoami | Displays the current username. | Built-in |
| clear | Clears the terminal screen. | ANSI |
| cls | Clears the terminal screen (Windows-style alias for clear). | ANSI |
| history | Shows a list of previously executed commands. | Built-in |
| sudo | Executes a command with superuser privileges. | Planned |
| tar | Creates, extracts, and manages tar archives. | Planned |
| zip | Compresses files in zip format. | Planned |
| unzip | Decompresses files from zip format. | Planned |
| echo | Outputs text to the terminal. | Built-in |
| help | Displays available terminal commands and their usage. | Built-in |
The Visual Interface.
| Term | Definition | Stack / Constraint |
|---|---|---|
| App Shell | The minimal HTML5 entry point (index.html). It contains zero business logic. Its only responsibility is to load the WASM binary and mount the Canvas/Div for the renderer. | → ui:wasm-driver | ⚙ Web Browser |
| WASM Driver | The strict Rust runtime in the browser. It replaces standard JavaScript logic, handling the WebSocket handshake, binary protocol deserialization, and piping raw events to the xterm renderer. | wasm-bindgen, web-sys | → net:nervous-system, ui:xterm |
| xterm | The rendering engine. It is treated as a "Dumb Display," strictly rendering the ANSI escape codes sent by the Backend Agent. | xterm.js |
| WebGPU Visualizer | A client-side component that renders the VectorGraph using a force-directed layout. It receives raw node/edge data from the Agent to visualize the "Brain." | wgpu |
| Dev Console | The secured developer interface mounted at /dev. It requires dual PSK authentication and provides self-modification capabilities: view source code, edit the Lexicon, trigger rebuilds, and rollback deployments. | Axum | → sys:axum-router, sys:root-harness, ui:code-browser, ui:code-editor, ui:rebuild-controller |
| Code Browser | File system viewer for /app source code. Renders file trees and file contents as HTML using pure Rust. No JavaScript required. | Axum, std::fs | → sys:axum-router |
| Code Editor | HTML form-based code editor. Uses textarea for editing, POST requests for saving. Writes directly to filesystem at /app/src. Pure Rust with no JavaScript dependencies. | Axum, std::fs | → ui:code-browser |
| Rebuild Controller | Triggers the self-modification pipeline: cargo build → docker build → docker push → kubectl rollout restart. Streams build logs back to the browser via Server-Sent Events. | Axum, tokio::process | → sys:root-harness |
| Rollback Controller | Executes kubectl rollout undo to revert to previous deployment. Provides safety mechanism for failed builds. | Axum, tokio::process | → sys:root-harness |
| WebSocket Terminal | Browser-based terminal using xterm.js (CDN) connected via WebSocket to Axum backend. Provides real-time bidirectional communication for executing shell commands. Pure Rust backend with no JavaScript compilation required. | Axum, tokio, futures | → sys:axum-router, ui:built-in-shell |
| Built-in Shell | Pure Rust command interpreter. Implements ls, cat, cd, pwd via std::fs, cp/mv/rm via fs_extra, and kubectl commands via kube-rs. No external process spawning for maximum stability and portability in scratch containers. | std::fs, fs_extra, kube-rs | → sys:fs-ops, sys:kube-client |
| FS Operations | File system operations using fs_extra crate. Provides copy, move, remove with progress tracking. Operates on /tmp workspace for editing files before rebuild. | fs_extra |
| Kube Client | Pure Rust Kubernetes client using kube-rs. Provides kubectl-like functionality: get pods/deployments, apply manifests, delete resources, rollout restart. Works with in-cluster service account or kubeconfig. | kube, k8s-openapi |