TPT-HiveForge

Distributed spatial coordination & swarm construction OS for a lunar build site.

A lunar city won't be built by one giant robot — it'll be built by thousands of heterogeneous robots (excavators, 3D printers, welders, transport bots) working simultaneously. Left alone, they'd collide, deadlock, or dig trenches through each other's work. HiveForge is a simulated, distributed operating system for swarm construction: a shared real-time spatial-awareness layer plus a decentralized task-allocation engine, so many robots can collaboratively build a sintered-regolith habitat without a central controller.

See spec.txt for the original design pitch and TODO.md for the full per-crate workstream breakdown, build order, and progress tracking.

Status

Every crate has a real implementation, and cargo test --workspace is fully green — unit tests, crate-level integration tests, a cross-cutting concurrency/chaos validation suite, and an 8-robot scale test all pass. See docs/KNOWN_LIMITATIONS.md for the honest list of what's still simulation-only, deferred, or a known rough edge — most notably, robot coordination currently runs in-process (one shared world state ticked per robot) rather than over the real hiveforge-net UDP mesh described below; that transport exists and is tested on its own, but isn't yet wired into the per-robot control loop.

How it works

Every robot runs a HiveForge node. Nodes continuously broadcast their position, intended trajectory, and current task over a local mesh network. A distributed, octree-based spatial hash divides the construction site into voxels; before a robot moves or builds, it claims the voxel. When two robots contend for the same voxel, a lightweight consensus protocol resolves the conflict deterministically by task priority. A "Trust & Verify" sensor fusion layer requires at least two independent localization modalities (visual odometry, IMU, UWB ranging) to agree before a position can back a claim, so degraded sensors can't silently corrupt the shared map.

Workspace layout

14 crates, one dependency rule: hiveforge-types has no internal dependencies, and nothing may create a cycle back into it.

Crate	Responsibility
hiveforge-types	Shared core types: VoxelCoord, RobotId, TaskId, Priority, Task, Pose, wire envelope.
hiveforge-spatial	Octree-based spatial hash map; voxel claim/release + TTL, conflict detection, range/neighbor queries.
hiveforge-net	Real UDP multicast mesh transport, discovery, and simulated loss/latency/partition injection.
hiveforge-consensus	Deterministic, priority-based conflict arbitration for contested voxel claims (Raft-lite, leaderless).
hiveforge-sensorfusion	Trust & Verify multi-modality position corroboration (visual odometry + IMU + UWB).
hiveforge-pathfinding	3D A* and D* Lite incremental replanning over the voxel grid.
hiveforge-blueprint	Parses a build shape-spec DSL, diffs it against site state, and decomposes it into a dependency-ordered task graph.
hiveforge-scheduler	Dependency-gated task release, capability matching, resource-aware assignment, and reassignment on robot failure.
hiveforge-resources	Battery/energy budgets, feedstock inventory, tool wear, and charging-station scheduling.
hiveforge-safety	Heartbeat/liveness and stuck-task detection, emergency-stop propagation, collision safety envelopes, black-box incident recording.
hiveforge-environment	Models lunar conditions (dust storms, thermal cycling, relay latency, radiation) as pure state, driving other crates' runtime knobs.
hiveforge-node	Per-robot runtime loop — the integration point where every subsystem above is wired together.
hiveforge-sim	Simulation harness, scenario runner, and the built-in scenario library.
hiveforge-server	Site-level telemetry/incident aggregation and a read-only text/JSON state view.

Getting started

cargo build --workspace              # build everything
cargo test --workspace               # run all unit + integration tests
cargo run -p hiveforge-sim --example run_scenarios   # run the built-in scenarios end-to-end

See hiveforge-sim/README.md for the scenario library and how to add new scenarios, and CLAUDE.md for a deeper architecture guide (commands, cross-cutting conventions, and known gotchas) aimed at contributors and coding agents alike.

License

MIT (see Cargo.toml).