$ cat /why.txt

Build agents that conserve energy. Literally.

Three-valued logic. Message-passing bottles. A conservation law you can prove at the type level. No frameworks. No buzzwords. Just math that compiles.

$ scroll down to run the demos

// core concepts — interactive

Ternary Classification {-1, 0, +1}

Every agent event resolves to one of three states. Negative, neutral, positive. No maybes. Click events below and watch the conservation balance.

classify events

// click events to classify

balance

Σ = 0

Bottle Protocol json+msgpack

JSON envelope for routing. msgpack for payload. Routers read the envelope without ever decoding the body. Click send and watch it round-trip.

bottle wire format

{ "src": "agent://alpha", "dst": "agent://bravo", "γ": 1, "η": -1, "payload": "0x82a3666f6f..." }

// waiting for send

Conservation Law γ + η = C

Gamma is energy injected. Eta is energy dissipated. Their sum is constant — like Gauss's law, but for agent networks. Adjust the sliders.

adjust parameters

γ (injection) 0.50

η (dissipation) 0.50

C = 1.00 ✓

drag a slider — the other auto-adjusts to conserve

// hello world — 43 lines of Rust

This compiles. This runs. This is the entire trait.

src/main.rs

use superinstance::{Agent, Bottle, Ternary};

/// Minimal agent: receive a bottle, respond with balance.
struct Balancer;

impl Agent for Balancer {
    fn receive(&mut self, bottle: Bottle) -> Bottle {
        let gamma = bottle.gamma();
        let eta   = bottle.eta();
        let c     = gamma + eta;          // conservation invariant
        let state = match c.classify() {
            Ternary::Positive  => "energy surplus",
            Ternary::Neutral   => "balanced",
            Ternary::Negative  => "energy deficit",
        };
        Bottle::new("balancer", bottle.src())
            .gamma(-eta)
            .eta(-gamma)
            .body(state)
            .seal()
    }

    fn inspect(&self) -> AgentState {
        AgentState::Active
    }
}

fn main() {
    let mut agent = Balancer;
    let msg = Bottle::new("you", "balancer")
        .gamma(1).eta(-1)
        .body("ping").seal();
    let reply = agent.receive(msg);
    println!("{}", reply.body());
}

// go deeper

hello world tutorial

Build your first conservation agent in 50 lines. Trits, bottles, and the conservation law — hands on.

read tutorial →

source code

Every crate, every test, every spec document. Read the code, not the docs.

github.com/superinstance →

SEED primitives

8 infrastructure crates. Circuit breakers, rate limiters, load balancers — all bottle-native.

browse crates →

spec documents

The math is formalized. Ternary conservation, bottle protocol, agent lifecycle — all specified.

read specs →