Shogunet

Networking integration for connecting multiple Shugocore agents together for collaboration between Shugocore agents in simulation and physical spaces, designed to be used over 5G, 4G, EDGE, LoRa, Wifi-Halow, Wifi, and Bluetooth networks.

Shogunet is the networking layer for ShugoCore. It lets a fleet of ShugoCore agents — running in Gazebo simulation, on servers, on robots, or on Android handsets — discover each other, exchange tasks and events, and consolidate a codependent memory mesh, over whatever networks the mission has available, with deterministic fallback between them.

Design principles

One protocol, every network. A single versioned envelope is spoken over all transports, from 5G to LoRa. Two codecs exist for it: a JSON codec for broadband links and a compact binary codec (16-byte header + TLV payload) for constrained links such as LoRa (0.3–27 kbit/s, ~220-byte frames) and BLE.

Memory invariants survive the network. ShugoCore's memory tiers map to network tiers: Tier 0/1 never leave the agent (N0). Tier 2 semantic facts sync between paired agents (N1). Tier 3 is read-only everywhere: only promotion proposals travel, and application stays operator-attributed (N2).

Codependent memory. Facts propagate with provenance (origin_agent_id, fact_id); salience merges additively; pruning propagates as tombstones; and reinforcement is a feedback loop — when a peer's fact proves useful, a tiny reinforce message flows back so useful memories survive decay fleet-wide. Over LoRa, the loop runs on ~50-byte digest frames; bulk fact content moves later over any broadband link (digest anti-entropy).

Pairing is consent. Only operator-allowlisted agent IDs pair, grants carry TTLs, topics are namespaced (/shugunet/{agent_id}/{topic}), and every ingress/egress field is sanitized and size-capped. Every network event lands in a hash-chained audit log.

Deterministic fallback. Transports form an ordered, health-ranked chain with per-transport circuit breakers. If the LAN drops, traffic falls to the relay; if everything drops, a bounded store-and-forward WAL replays on reconnect. Total transport exhaustion latches the ShugoCore governor through its fallback triggers instead of failing silently.

Network tiers

Message priority classes: P0 control (announce/heartbeat/ack/tombstone) → all links · P1 memory deltas (facts/reinforce/digests) → constrained-capable · P2 tasks and queries → IP links · P3 bulk snapshots and audit shipping → broadband only, deferred under low power / thermal pressure.

Module map

Hosting a fleet

Shogunet runs as a single server process that owns the fleet's trust plane so every ShugoCore agent only needs a ~20-line client runtime to join.

Start a host

from host import ShugonetHost

host = ShugonetHost(agent_id="fleet-1", tcp_port=9000, relay_port=9001)
host.start()

# Grant consent to a joining agent (pairing = consent)
host.pair("agent-001", manifest={"realm": "phys", "role": "perception"})

print(host.status())   # roster, alive count, breaker health, mesh counts

Or from the CLI:

python3 host.py --tcp-port 9000 --relay-port 9001

Join from a ShugoCore process

from agent_runtime import ShugonetAgentRuntime

runtime = ShugonetAgentRuntime(
    agent_id="agent-001",
    host_tcp_host="127.0.0.1",
    host_tcp_port=9000,
    host_relay_url="http://127.0.0.1:9001",
    on_message=lambda sender, msg: print(f"from {sender}: {msg}"))
runtime.connect_to_host()

# Send a task to another agent
runtime.send("agent-002", "/shugunet/agent-001/task",
             {"action": "scan", "zone": "north"})

# Search the fleet's memory
results = runtime.query("obstacle in zone north")

# Sync memory with the fleet
runtime.sync()

# Leave the fleet
runtime.stop()

Routing model

Agents connect to the host (hub-and-spoke). The host forwards addressed mail to its recipient and fans broadcasts out as addressed copies to every other paired agent. Host-addressed mail — heartbeats, mesh queries, memory broadcasts — is processed locally by the host's own chain handlers.

Pairing is enforced twice — at TCP admission (handshake hook) and again on every host-processed or forwarded envelope (the relay path has no registry gate of its own, so the host re-checks the sender there).

Failure semantics

• Agent crash/disconnect → host governor latches pause (ShugoCore deterministic latch contract).
• Message durability → per-agent OutboxStore + at_least_once QoS + hub mailbox TTL bounds.
• Cross-talk → chain and mesh recipient guards (hardened in the concurrency suite) hold at host scale.

Module map (continued)

Testing

python3 -m unittest discover -s tests -v

The suite is dependency-free and runs everywhere: transports are exercised through the loopback bus and the in-process link simulator, which models every network's bandwidth, latency, loss, MTU and duty-cycle constraints. The integration suite spins up a real ShugonetHost with multiple threaded ShugonetAgentRuntime clients, validates cross-talk isolation, memory convergence, peer-lost latching, and unpaired-agent refusal.