ternary-captain: Captain/leadership pattern for fleet coordination

Why This Exists

A fleet of agents needs leadership — not a single point of failure, but a pattern where one agent coordinates others, delegates work, and makes decisions. This crate implements the PLATO captain concept: a lead agent that weighs ternary options, assigns tasks by specialization, aggregates sensor data, and maintains a succession plan for when leadership must transfer.

Core Concepts

Captain: The lead agent. Maintains a roster, makes decisions via the DecisionEngine, delegates tasks, and tracks succession.

Ternary decisions: Choices are always three-valued: Negative (reject/retreat), Zero (abstain/gather info), Positive (accept/advance). The DecisionEngine aggregates votes into a fleet decision.

Quorum: Minimum number of votes required before a decision is valid. Prevents a single agent from deciding for the fleet.

Delegation: Tasks are assigned to agents by matching task type to agent specialization, breaking ties by fitness score.

Succession plan: Ordered list of successors. If the captain becomes unavailable, the next in line takes over. Prevents orphaned fleets.

Quick Start

[dependencies]
ternary-captain = "0.1"

use ternary_captain::{Captain, AgentInfo, AgentStatus, Ternary, DecisionEngine};

let mut captain = Captain::new("cap-1", 2); // quorum of 2

captain.enlist(AgentInfo {
    id: "scout-1".into(),
    status: AgentStatus::Ready,
    specialization: "recon".into(),
    fitness: 0.9,
});
captain.enlist(AgentInfo {
    id: "medic-1".into(),
    status: AgentStatus::Ready,
    specialization: "medical".into(),
    fitness: 0.7,
});

// Delegate a recon task
let assigned = captain.delegate("patrol-north", "recon");
assert_eq!(assigned, Some("scout-1".to_string()));

// Make a fleet decision
let votes = vec![Ternary::Positive, Ternary::Positive, Ternary::Zero];
let decision = captain.decide_from_votes(&votes);
assert_eq!(decision, Some(Ternary::Positive));

API Overview

Type	What it is
`Captain`	Lead agent with roster, decisions, delegation, and succession
`DecisionEngine`	Aggregates ternary votes with quorum requirement
`Delegator`	Assigns tasks to best-fit agents by specialization and fitness
`SituationRoom`	Aggregates ternary sensor reports into fleet-wide picture
`FleetReport`	Status rollup: health ratio, operational status, offline agents
`SuccessionPlan`	Ordered succession line with promote/remove operations
`AgentInfo`	Agent record: id, status, specialization, fitness
`AgentStatus`	Ready, Busy, Offline, or Compromised

How It Works

The DecisionEngine uses simple majority voting. On ties, the priority order is Negative > Zero > Positive (conservative bias). Weighted voting allows higher-fitness agents to have more influence.

Delegation scans the roster for agents that match the task's specialization and are in Ready status, then picks the highest-fitness match. This is O(n) per delegation — fine for typical fleet sizes but not optimized for thousands of agents.

The SituationRoom collects ternary reports and aggregates them the same way as decisions: majority vote. This gives a fleet-level ternary picture from individual agent perspectives.

Succession is a simple ordered list. When the captain transfers, promote_next() removes the heir from the line and the next agent becomes heir. This is deliberate — it models military succession, not democratic election.

Known Limitations

Tie-breaking is arbitrary: When votes are evenly split, the result depends on enum ordering, not strategic reasoning. Real fleets may need configurable tie-breaking.
No vote verification: The system trusts all votes equally. Malicious agents can manipulate decisions by submitting strategically timed votes.
Single-level hierarchy: No support for captains-of-captains. Deep hierarchies require composing multiple Captain instances manually.
No time-based decisions: Votes aren't timestamped. Late votes count the same as early ones.

Use Cases

Room leadership: One agent coordinates sensors and actuators in a physical room.
Fleet task distribution: Assign exploration, maintenance, or repair tasks to specialists.
Consensus decisions: Multiple agents vote on whether to enter a room, trigger an alert, or stand down.
Graceful leadership transfer: When a room's captain agent is replaced, the succession plan ensures continuity.

Ecosystem Context

Part of the SuperInstance ternary ecosystem. The captain pattern maps directly to the PLATO concept and capitaine-1's flagship role:

ternary-agent provides the Agent types that populate the roster
ternary-tidelight synchronizes when captains make decisions (tick-aligned)
ternary-flux can flow decisions through the system
ternary-muse can generate creative ternary patterns for decision exploration

No external dependencies — pure Rust.

License

MIT

ternary-captain 0.1.0