Shivya: The Non-Dual Distributed Computing Substrate

Shivya is a bare-metal, zero-dependency, edge-native runtime: a consensus-free localized resource diffusion balancer for edge hardware arrays, built on Discrete Exterior Calculus and Variational Free Energy minimization. It is not a drop-in replacement for Paxos or Raft. The contributions are (i) a Hodge-projector that removes curl from concurrent edge-state deltas after partition heal, and (ii) a multi-agent Active-Inference loop that diffuses load through symmetric Onsager couplings. The underlying mathematics is referenced in CITATIONS.md.

The 5-Layer Architectural Stack

graph TD
    Layer4["Layer 4: Turing Morphogenesis (Topology Adaption)"] --> Layer3["Layer 3: Onsager Ensemble (Reciprocal Flow Diffusion)"]
    Layer3 --> Layer2["Layer 2: Morphic Core (Metamorphic VM & State Expansion)"]
    Layer2 --> Layer1["Layer 1: Gibbs Flux (Variational Active Inference)"]
    Layer1 --> Layer0["Layer 0: Hodge Mesh (Simplicial Boundary Reconciler)"]

Layer 0: Topological Fabric shivya-hodge

• Core Abstraction: Simplicial State Complexes and Discrete Exterior Calculus (DEC).
• Function: Solves structural boundary flow equations using an iterative Conjugate Gradient solver. It partitions concurrent network partitions into a gradient flow (non-conflicting mutations) and a curl flow (rotational conflict loops), projecting out the curl to arrive at consistent states deterministically without time locks.

Layer 1: Predictive Homeostasis shivya-flux

• Core Abstraction: Variational Free Energy Principle (FEP).
• Function: Represents nodes as Active Inference Agents bound by statistical Markov Blankets. Nodes minimize Variational Free Energy ($F$) via continuous gradient descent over internal belief parameters to adapt to non-stationary sensorimotor telemetry.

Layer 2: Autotelic Morphic Core shivya-morphic

• Core Abstraction: Metamorphic VM Hot-Swapping & State Space Expansion.
• Function: Evaluates structural update loops inside a sandboxed, stack-allocated Register VM with strict instruction cycle budgets. When moving average free energy breaches novelty thresholds, the node expands its generative state dimensions (e.g., from 2D to 3D) and rewrites its execution bytecode.

Layer 3: Thermodynamic Collective Ensemble shivya-onsager

• Core Abstraction: Onsager Reciprocal Relations & Game-Theoretic FEP.
• Function: Regulates parameter and workload migration across blankets via symmetric conductance couplings ($L_{ij} = L_{ji}$). Computes global Collective Free Energy ($\mathcal{F}_{\text{collective}}$) by resolving Harsanyi dividends recursively over adjacent neighbor coalitions to enforce cooperative synergy.

Layer 4: Morphogenetic Pattern Substrate shivya-turing

• Core Abstraction: Non-linear Graph Reaction-Diffusion & Network Plasticity.
• Function: Solves activator-inhibitor partial differential equations using Runge-Kutta 4th Order (RK4) integration with dynamic CFL stability guards. High-stress activator hotspots trigger pre-allocated object-pool mesh topology updates (node splits without runtime heap resizing crashes), while low-utility nodes undergo apoptosis (culling) to optimize global resource usage.

Decentralized P2P Mesh Architecture

To unify geographically separated hardware edge daemons into a cooperative statistical field, Shivya utilizes a decentralized peer-to-peer transport layer (crates/shivya-p2p):

• XOR Kademlia Routing (src/routing.rs): Nodes generate a unique 160-bit identifier (NodeId) and maintain stack-allocated K-buckets ($K=4$). Stale nodes are kept at bay using an active LRU Ping Eviction Guard.
• Kademlia RPC primitives (src/transport.rs): Full PING / PONG / FIND_NODE / FOUND_NODES / STORE / FIND_VALUE / FOUND_VALUE set, with bounded-size frames (≤ 1 MTU, no UDP fragmentation) and an iterative discovery loop that walks returned peers via successive PINGs. A local DHT key/value store sits behind STORE/FIND_VALUE.
• Thermodynamic UDP Framing (src/protocol.rs): Fixed-layout binary serialization (Big-Endian floats) for the control- and state-plane payloads carried over the same socket.
• Partition-test hook: Each transport exposes a block(addr) / unblock(addr) API that drops outbound frames to a given address. This is used by tests/jepsen_partitions.rs to inject controllable partitions across five real localhost UDP nodes and assert that the Layer-0 Hodge projector wipes out the curl introduced by the split.

Native Edge Daemon CLI (shivya-cli)

Shivya includes a native command-line daemon (crates/shivya-cli) configured with a multi-threaded Tokio runtime. It samples real host telemetry via the sysinfo crate (CPU load, network bytes RX/TX, memory utilisation ratio) to step the 5-layer active-inference substrate, and bridges topology splits and state updates to the optional visualizer dashboard.

CLI Daemon Commands & Options

The CLI start subcommand supports several options to configure the peer-to-peer network and live visualization bridge:

• --port <PORT>: The UDP port to bind the P2P transport listener (defaults to 8085).
• --peer <ADDR:PORT>: Optional address of an existing peer to bootstrap into the causal simplicial network. Triggers an immediate PING followed by a FIND_NODE(self) to seed the iterative bucket-discovery walk.
• --visualize: Spawns a non-blocking WebSocket server on 127.0.0.1:9002 to stream the latest orchestrator status JSON to the observability dashboard.
• --daemon (unix only): Performs a true fork() + session detach via the daemonize crate before the Tokio runtime is built. Writes its PID to /tmp/shivya.pid and redirects stdout / stderr to /tmp/shivya.out and /tmp/shivya.err. The Tokio reactor then starts inside the detached child so I/O descriptors survive after the launching shell closes.

Running the CLI Daemon

1. Start a Seed Node with Live Visualization:

   cargo run --release -p shivya-cli -- start --port 8085 --visualize
   

   Note: On startup, the daemon automatically cleans up any stale Unix Domain Sockets (UDS) and binds safely to /tmp/shivya_cli.sock.

2. Boot up a Bootstrap Peer Node: Connects to the seed node, building a mutual causal simplicial network:

   cargo run --release -p shivya-cli -- start --port 8086 --peer 127.0.0.1:8085
   

3. Query Substrate Registry Status: Connects to the local background UDS server to fetch and print the real-time active inference, VM mutation, and topological metrics:

   cargo run --release -p shivya-cli -- status
   

4. Graceful Teardown: Send a SIGINT (Ctrl+C) or SIGTERM signal to trigger orderly apoptotic memory cleanup, unbind the socket file, and notify connected peers.

Rust Integration Example

use shivya::hodge::complex::SimplicialStateComplex;
use shivya::flux::model::GibbsFluxAgent;
use shivya::morphic::{DynamicGibbsAgent, MorphicHotSwapper, Expr};
use shivya::onsager::OnsagerCollectiveEnsemble;
use std::thread;
use std::time::Duration;

fn main() {
    println!("Initializing Shivya Substrate...");

    // 1. Establish initial 3-node topology
    let mut adjacent_nodes = vec![
        vec![1, 2], // Node 0 neighbors
        vec![0, 2], // Node 1 neighbors
        vec![0, 1], // Node 2 neighbors
    ];

    // 2. Set up Gibbs Active Inference Agents
    let create_agent = |mu_prior: f64| {
        DynamicGibbsAgent::new(
            2, 1, 2,
            vec![mu_prior, 0.0],
            vec![vec![10.0, 0.0], vec![0.0, 10.0]],
            vec![vec![1.5, 0.0], vec![0.0, 1.5]],
            vec![vec![0.1, 0.0], vec![0.0, 0.1]],
            vec![vec![0.0], vec![0.0]],
            vec![vec![0.0], vec![0.0]],
            vec![0.0, 0.0],
            vec![vec![1.0, 0.0], vec![0.0, 1.0]],
            5.0, // Novelty threshold
        )
    };

    let agents = vec![
        create_agent(0.1),
        create_agent(0.2),
        create_agent(0.15),
    ];

    // 3. Construct the Onsager Collective Ensemble
    let mut ensemble = OnsagerCollectiveEnsemble::new(agents, adjacent_nodes, 0.5);

    // 4. Run the homeostatic execution loop inside a runtime thread
    let handle = thread::spawn(move || {
        let observations = vec![
            vec![1.2, 0.8], // Node 0 sensory inputs
            vec![2.0, 1.1], // Node 1 sensory inputs
            vec![1.5, 0.9], // Node 2 sensory inputs
        ];

        for step in 1..=5 {
            let collective_f = ensemble.step(
                &observations,
                0.1,   // Learning rate
                10,    // Max belief iterations
                1e-4,  // Convergence tolerance
                0.1    // Onsager migration rate
            );
            println!("Step {} -> Collective Free Energy: {:.6}", step, collective_f);
            thread::sleep(Duration::from_millis(50));
        }
    });

    handle.join().unwrap();
    println!("Homeostatic loop terminated stably.");
}

Crate Layout & Distribution namespaces

All core modules are zero-dependency, stack-allocated, and target WebAssembly (wasm32-unknown-unknown):

• crates/shivya-hodge - Layer 0 Simplicial exterior calculus
• crates/shivya-flux - Layer 1 Homeostatic Active Inference agent
• crates/shivya-morphic - Layer 2 Sandboxed metamorphic register VM
• crates/shivya-onsager - Layer 3 Thermodynamic multi-agent ensemble
• crates/shivya-turing - Layer 4 Network reaction-diffusion morphogenesis
• crates/shivya-p2p - Decentralized Kademlia P2P transport & UDP network mesh
• crates/telemetry_wasm - Unified Substrate WASM telemetry bindings
• crates/shivya-cli - High-performance native background daemon & Tokyo-UDS CLI tool

License

This framework is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE-MIT and LICENSE-APACHE for details.