Core Concepts

Conservation Law (γ + η = C) #

Every agent operation has two energy components: generation (γ) — useful work done — and entropy (η) — waste, retries, confusion. Their sum is a constant C. You can't reduce one without increasing the other.

This isn't abstract math. It's a budgeting tool. If a ship spends 0.3 of its energy on retries and misrouted messages (η = 0.3), then only 0.7 of its energy went toward actual output (γ = 0.7). The total is always C = 1.0.

Concrete example:

// Operation audit for ship "cargo-inspector"
Generation (γ) = 0.72   // crates inspected, reports filed
Entropy     (η) = 0.28   // 3 retries, 1 timeout, 2 duplicate messages
Total       (C) = 1.00   // conservation holds

// Fleet rule: reject operations where η > 0.40
if (entropy > 0.40) {
    throttle_ship(ship_id);
}

Fleet Model #

SuperInstance organizes agents into a three-tier hierarchy: Ships (individual agents), Fleets (coordinated groups), and the SuperInstance itself (the bird's-eye view of everything).

Think of it like a container orchestrator, but for AI agents instead of containers. Each ship owns its own git repo, runs autonomously, and reports to a captain agent (cocapn) that coordinates work across the fleet.

• Ship — single autonomous agent. Git-native, owns a repo, has its own identity and energy budget.
• Fleet — collection of ships coordinated by a captain. Handles routing, load balancing, and cross-ship communication via bottles.
• SuperInstance — the meta-layer. Sees all fleets, enforces global policies, runs vector search and semantic indexing.

# fleet.yaml — define a ship in your fleet
ships:
  cargo-inspector:
    repo: git://fleet/cargo-inspector
    role: inspection
    energy:
      max_entropy: 0.40
      budget_per_cycle: 100
    tags: [crates, quality, inspection]

  route-planner:
    repo: git://fleet/route-planner
    role: logistics
    energy:
      max_entropy: 0.35
      budget_per_cycle: 150
    tags: [routes, optimization]

captain:
  id: cocapn
  strategy: round-robin
  max_concurrent: 8

Ternary Computing {-1, 0, +1} #

SuperInstance uses three-valued logic instead of binary. A ternary signal can be negative, neutral, or positive — which maps naturally to how agents make decisions, vote on proposals, and score quality.

This isn't theoretical. Every conservation audit produces a ternary verdict: the ship is performing above baseline (+1), at baseline (0), or below baseline (-1). Fleet-level decisions aggregate these signals across all ships.

/// Ternary value used across the fleet for
/// decision-making, voting, and quality signals.
pub enum Ternary {
    Neg  = -1,  // disagree / below baseline / negative signal
    Zero = 0,   // neutral / at baseline / no signal
    Pos  = 1,   // agree / above baseline / positive signal
}

/// Aggregate ternary signals from multiple ships.
pub fn aggregate(signals: Vec<Ternary>) -> Ternary {
    let sum: i32 = signals.iter().map(|t| *t as i32).sum();
    match sum {
        s if s > 0 => Ternary::Pos,
        s if s < 0 => Ternary::Neg,
        _       => Ternary::Zero,
    }
}

Bottles Protocol #

Bottles are the message-passing units between agents. Every inter-ship communication is a bottle — a structured envelope with routing headers, a typed payload, and a label that tells the receiver what to do with it.

The flow is always: Ship A seals a bottle → the Fleet captain routes it → Ship B opens it. Ships never talk directly. This lets the captain enforce policies, log messages, and rebalance work mid-flight.

{
  "bottle": {
    "header": {
      "from": "cargo-inspector",
      "to": "route-planner",
      "trace_id": "btl_a3f9c2",
      "timestamp": "2026-06-12T17:00:00Z"
    },
    "body": {
      "crate_id": "CR-4081",
      "quality_score": 0.93,
      "flagged": false
    },
    "label": "inspection.complete"
  }
}

T-Minus Dispatcher #

T-Minus is SuperInstance's temporal coordination system. It dispatches cues on a countdown basis rather than fixed schedules. Think of it like cron, but event-driven with countdown semantics — you schedule an action to fire in N seconds, not at a wall-clock time.

Packages: @superinstance/tminus-client (what ships use) and @superinstance/tminus-dispatcher (the server-side coordinator).

import { TMinusClient } from '@superinstance/tminus-client';

const client = new TMinusClient();

// Schedule a deploy cue in 60 seconds
await client.schedule('deploy', { countdown: 60 });

// Listen for when it fires
client.on('cue', (cue) => {
  console.log(`Firing: ${cue.action}`);
  runDeploy();
});

// Cancel if conditions change
client.cancel('deploy');

Vector Search & Semantic Index #

SuperInstance indexes 1,541 crates using BAAI/bge-small-en-v1.5 embeddings (384 dimensions). Three API endpoints let ships and external clients search by meaning, find similar crates, and get composite recommendations.

The /recommend endpoint combines semantic similarity with quality signals (ternary scores from inspections) to rank results — not just "closest vector" but "best overall fit."

# Search by natural language
curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{"query": "rust async runtime", "topK": 5}'

# Find crates similar to a known crate
curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/similar \
  -H "Content-Type: application/json" \
  -d '{"crateId": "tokio", "topK": 5}'

# Composite: semantic + quality signals
curl -X POST https://fleet-vector-api.casey-digennaro.workers.dev/recommend \
  -H "Content-Type: application/json" \
  -d '{"query": "http client", "topK": 5, "minQuality": 0.8}'