SHIVYA Technical Architecture

1. Component Layout

SHIVYA is constructed as a modular Rust virtual workspace. It enforces strict boundary conditions, decoupling core homeostatic computations from platform-specific asynchronous networking and telemetry collection routines.

graph TD
    classDef ui fill:#0F172A,stroke:#F43F5E,stroke-width:2px,color:#F8FAFC;
    classDef run fill:#0F172A,stroke:#10B981,stroke-width:2px,color:#F8FAFC;
    classDef net fill:#0F172A,stroke:#14B8A6,stroke-width:2px,color:#F8FAFC;
    classDef core fill:#0F172A,stroke:#3B82F6,stroke-width:2px,color:#F8FAFC;

    Dashboard["WebOS Dashboard (index.html)"]:::ui
    CLI["shivya-cli (Tokio & UDS)"]:::run
    WS["WebSocket Server (Port 9002)"]:::run
    P2P["shivya-p2p (Kademlia & UDP)"]:::net
    UDP["Thermodynamic UDP Port"]:::net

    L4["Layer 4: shivya-turing (Morphogenesis)"]:::core
    L3["Layer 3: shivya-onsager (Thermodynamics)"]:::core
    L2["Layer 2: shivya-morphic (Morphic VM)"]:::core
    L1["Layer 1: shivya-flux (Gibbs Inference)"]:::core
    L0["Layer 0: shivya-hodge (DEC Matrix Solver)"]:::core

    Dashboard <-->|WebSocket Stream| WS
    WS <-->|SystemStatus JSON| CLI
    CLI -->|Steps Ensemble| L4
    L4 --> L3 --> L2 --> L1 --> L0
    
    CLI <-->|Routes Events| P2P
    P2P <-->|Big-Endian UDP Packets| UDP
    UDP <-->|Network Mesh| PeerNode["Peer Edge Node"]:::net
                

2. Core Crate Layer Specifications

Layer 0: Topological Fabric (crates/shivya-hodge)

Tracks event history inside a directed simplicial complex and reconciles conflict using DEC operators:

• SimplicialStateComplex: Tracks vertices (events), edges (directed flows), and triangles (concurrent context boundaries).
• DEC Operators: Implements gradient (\(d_0\)), curl (\(d_1\)), and divergence (\(\delta_1 = d_0^T\)) operators.
• Conjugate Gradient Solver: A sparse solver optimized for symmetric positive semi-definite (SPSD) systems that runs with zero heap allocations.
• Geodesic Reconciler: Projects out rotational conflict flow (\(d_1^T \beta\)) by solving:
  \[L_2 \beta = d_1 \Delta S \quad \text{where} \quad L_2 = d_1 d_1^T\]

Layer 1: Homeostasis (crates/shivya-flux)

Steps physical nodes as Active Inference agents. Agents maintain internal beliefs (\(\mu\)) and adapt to environmental fluctuations by minimizing Variational Free Energy (\(F\)) over sensory streams (\(s\)) via local continuous gradients.

Layer 2: Autotelic Morphic Core (crates/shivya-morphic)

Evaluates state transition logic inside a stack-allocated Register VM with cycle budgets. If moving average free energy breaches novelty limits, the VM hot-swaps its instruction stream and expands its active state dimensions.

Layer 3: Thermodynamic Ensemble (crates/shivya-onsager)

Coordinates adjacent node blankets using Onsager Reciprocal Relations and Game-Theoretic FEP. Balances resource migration across symmetric conductance couplings (\(L_{ij} = L_{ji}\)).

Layer 4: Morphogenesis (crates/shivya-turing)

Solves activator-inhibitor partial differential equations using Runge-Kutta 4th Order (RK4). High-stress activator zones trigger vertex mitosis (node splits), while low-utility zones undergo apoptosis (culling).

3. Decentralized Kademlia Transport (crates/shivya-p2p)

Binds geographically separated daemons into a unified statistical causal field using a custom peer-to-peer UDP protocol:

• Kademlia XOR Routing Table: Nodes maintain stack-allocated routing tables ($K=4$) keyed by XOR distance (\(d(x,y) = x \oplus y\)).
• LRU Eviction Guard: Full buckets trigger asynchronous UDP pings to detect stale addresses, preserving network topological health.
• Thermodynamic UDP Wire Protocol: Zero-heap, Big-Endian float packet serialization to transfer simplicial splits and parameter variations seamlessly across diverse CPU architectures.

4. Native Edge Daemon & Visualizer Bridge (crates/shivya-cli)

Acts as the orchestrator running the multi-threaded Tokio runtime on bare-metal:

• System Sampler: Pulls real-time CPU load and network packet metrics using `sysinfo` to drive the active inference loop.
• WebSocket Telemetry Bridge: When booted with --visualize, spawns a TCP server on port 9002 using tokio-tungstenite to broadcast JSON-serialized state snapshots.
• Lagged Recovery Loop: Gracefully catches RecvError::Lagged events, bypassing blocked or throttled browser clients to protect the core compute loop from backpressure.