Songbird - Network Orchestration & Discovery Primal

Version: v0.2.1
Status: Production Ready - Deep Debt S+ Tier
License: AGPL-3.0-or-later (scyBorg provenance trio)
Edition: Rust 2024

Songbird is the universal network orchestrator for the ecoPrimals ecosystem. It manages service discovery, connection management, and inter-primal communication across multiple protocols. All cryptographic operations are delegated to the security provider capability (security.sock / SECURITY_PROVIDER_SOCKET) via JSON-RPC IPC at runtime through capability-based discovery.

Quality

Metric	Value
Safe Rust	100% (#![forbid(unsafe_code)] across all 30 crates; zero unsafe blocks)
Pure Rust	100% — native QUIC engine with security provider crypto delegation; rcgen eliminated (pure Rust test cert gen via ed25519-dalek + DER); ring-crypto opt-in feature gate remains on CLI only
Crypto Delegation	Security provider via JSON-RPC IPC — TLS record layer, JWT, checkpoints, discovery, rendezvous all delegate via CryptoProvider::call(); graceful local fallback + tracing::warn!
Runtime Discovery	All config: env → XDG → smart defaults; capability-based biomeos socket probing; netdev-based IP detection; all ports env-configurable (SONGBIRD_DISCOVERY_PORT, SONGBIRD_STUN_PORT, SONGBIRD_RELAY_PORT); XDG-compliant socket paths
Production panics	Zero (panic!(), unreachable!(), todo!() only in #[cfg(test)])
Production .unwrap()	Zero (all in test modules — verified via line-by-line audit)
Production FIXME/HACK	Zero
Lint suppressions	#[expect(reason)] where lint fires in production; #[allow(reason)] only in #[cfg(test)] modules; production dead_code allows removed (Apr 6 audit)
Concurrent Tests	Injectable _with env readers; all tests fully concurrent; #[serial_test] fully eliminated (0 suites); tokio::time::pause() for deterministic timing
Tests	12,764 passed, 0 failed, 252 ignored
Line Coverage	72.16% (llvm-cov --workspace --lib, Apr 6 2026; target 90%)
Cast Safety	cast_possible_truncation, cast_sign_loss, cast_precision_loss, cast_possible_wrap denied workspace-wide
JSON-RPC Strict	Version validation, notification suppression, serialization-safe fallbacks across all 5 handlers
JSON-RPC Dispatch	Typed JsonRpcMethod enum routing (53+ methods, 14 domain sub-enums) — zero string matching in dispatch; birdsong.schema introspection
Clippy Pedantic	All 30 crates clean (clippy::pedantic + nursery, zero warnings, --all-targets --all-features)
Build	Clean (zero errors, zero warnings)
Formatting	Clean (cargo fmt --check; Apr 6 audit: no drift)
Docs	Clean (RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps)
Files >800 lines	0 (largest file 519 lines; tower_atomic.rs refactored into 4 modules)
License	AGPL-3.0-or-later via workspace inheritance; all crates use license.workspace = true (Apr 6: AGPL-3.0-only drift eliminated)
SPDX Headers	100% of .rs files have AGPL-3.0-or-later — consistent with Cargo.toml and LICENSE body (Apr 6 audit)
JSON-RPC Gateway	53+ semantic methods across 14 domain sub-enums (health, discovery, stun, relay, federation, tor, birdsong, ipc, etc.)
Nest Atomic	health.liveness + health.readiness + health.check + capabilities.list (14 capability tokens)
Method Normalization	normalize_json_rpc_method_name() in songbird-types; handles ecosystem naming drift
Lint Inheritance	30/30 crates inherit workspace lints; 2 with justified custom tables
cargo-deny	Fully passing (advisories ok, bans ok, licenses ok, sources ok)
Dependencies	sled feature-gated with in-memory fallback; kube/k8s-openapi/bollard feature-gated; Bluetooth native C deps only with bluetooth feature
UniBin	Single binary: server, cli (REPL), compute-bridge, deploy, rendezvous
Total Rust	~423,800 lines across 30 crates (1,573 files)

Architecture

Application Layer (biomeOS Neural API, AI Coordination, Compute)
    |
    | JSON-RPC 2.0 + tarpc
    v
Songbird Orchestrator
    |-- Tor Protocol (pure Rust: directory, circuit, stream, onion service)
    |-- Sovereign Onion (P2P encrypted service + connector)
    |-- IGD Router Config (UPnP IGD + NAT-PMP, auto port forwarding)
    |-- QUIC Transport (native Rust — RFC 9000/9001/9002, security provider crypto, 0-RTT, migration)
    |-- NFC Genesis (Dark Forest mobile pairing, zero metadata leakage)
    |-- BLE GATT (Bluetooth Low Energy genesis)
    |-- TLS 1.3 (RFC 8446, protocol detection)
    |-- STUN Server (RFC 5389, NAT discovery, port pattern probing)
    |-- Relay Server (lineage-based auth, packet forwarding, coordinated punch)
    |-- Dark Forest Discovery (encrypted beacons, mDNS, DNS-SD)
    |-- Universal IPC (Unix sockets, TCP, platform-agnostic)
    |
    | Security capability delegation (Ed25519, X25519, ChaCha20, SHA3-256, AES-128-CTR)
    v
Security Provider (capability discovery: security.sock / SECURITY_PROVIDER_SOCKET)

Core Principles

1. Self-Knowledge Only - Each primal knows only itself
2. Runtime Discovery - All external services discovered at runtime by capability
3. Capability-Based - Request by capability, not by name
4. Zero Hardcoding - Environment-first configuration
5. Pure Rust - Zero C dependencies in Songbird code (ecoBin compliant)
6. Safe Rust - #![forbid(unsafe_code)] everywhere
7. Event-Driven - Zero polling anti-patterns (tokio::sync::Notify)
8. Concurrent Testing - Injectable _with env readers for fully concurrent tests
9. JSON-RPC + tarpc First - Primary IPC protocols

Quick Start

cargo build --workspace --release
cargo run --bin songbird -- server
cargo run --bin songbird -- doctor
cargo run --bin songbird -- config show
cargo run --bin songbird -- compute-bridge
cargo run --bin songbird -- deploy

Environment Variables

export SECURITY_PROVIDER_SOCKET=/run/user/$(id -u)/biomeos/security.sock
export NEURAL_API_SOCKET=/run/user/$(id -u)/biomeos/neural-api.sock
export SONGBIRD_HTTP_PORT=3492
export SONGBIRD_BIND_ADDRESS=0.0.0.0
export SONGBIRD_IGD_ENABLED=true
export SONGBIRD_FAMILY_ID=myfamily
export SONGBIRD_DISCOVERY_PORT=2300
export SONGBIRD_STUN_PORT=3478
export SONGBIRD_RELAY_PORT=3479
export SONGBIRD_ROUTE_DETECT_ADDR=192.0.2.1:80

Crate Structure (30 crates)

Core

• songbird-orchestrator - Main orchestration engine (7-stage startup)
• songbird-cli - Command-line interface (UniBin)
• songbird-config - Configuration management
• songbird-types - Shared type definitions
• songbird-canonical - Canonical type system

Networking

• songbird-universal-ipc - Platform-agnostic JSON-RPC IPC
• songbird-http-client - Pure Rust TLS 1.3 HTTP client
• songbird-network-federation - Peer federation + rendezvous
• songbird-discovery - Service discovery (mDNS, DNS-SD, Dark Forest)
• songbird-igd - UPnP IGD + NAT-PMP router config

Protocols

• songbird-tor-protocol - Pure Rust Tor (directory, circuit, stream, onion)
• songbird-tls - TLS 1.3 implementation
• songbird-stun - STUN server RFC 5389
• songbird-quic - Pure Rust QUIC transport (RFC 9000, security provider crypto delegation, 0-RTT, migration)
• songbird-sovereign-onion - P2P onion service
• songbird-lineage-relay - Lineage relay + coordinated punch
• songbird-onion-relay - Hole punch coordinator

Hardware

• songbird-nfc - NFC genesis protocol
• songbird-bluetooth - BLE GATT service
• songbird-genesis - Physical genesis bootstrap

Crypto

• songbird-crypto-provider - Shared crypto provider (Neural API + direct security provider routing)

Shared

• songbird-universal - Universal capability adapters
• songbird-primal-coordination - Primal coordination
• songbird-registry - Service registry
• songbird-observability - Metrics and tracing
• songbird-execution-agent - Task execution
• songbird-compute-bridge - Compute bridge (UniBin subcommand)
• songbird-remote-deploy - Remote deployment (UniBin subcommand)
• songbird-test-utils - Test utilities
• songbird-process-env - Safe env var facade for Rust 2024 (unsafe isolation)

Sovereign Beacon Mesh

Songbird provides a sovereign beacon mesh for encrypted peer discovery and relay coordination. The validated call sequence:

mesh.init            → Initialize mesh with node_id, family_id, listen endpoints
mesh.announce        → Announce presence as relay (advertise capabilities)
mesh.peers           → List reachable peers (direct, relay, onion, LAN)
mesh.status          → Mesh topology, reachable count, path types

Additional methods: mesh.find_path (best route to peer), mesh.health_check (probe peer connections), mesh.auto_discover (scan for new peers).

See specs/SOVEREIGN_BEACON_MESH_SPECIFICATION.md for the full protocol specification.

Testing

cargo test --workspace --all-features          # Full suite (12,764 tests, ~70s)
cargo test -p songbird-tor-protocol --lib      # Single crate
./scripts/test-with-security-provider.sh        # With live security provider from plasmidBin
./scripts/coverage.sh                          # llvm-cov HTML report

Documentation

Document	Purpose
REMAINING_WORK.md	Current status, metrics, and pending work
CHANGELOG.md	Version history
CONTRIBUTING.md	Contribution guidelines
CONTEXT.md	AI-ingestible project context
specs/	Technical specifications
docs/architecture/	Security provider crypto API spec, sovereign onion architecture

License

AGPL-3.0-or-later (scyBorg provenance trio: AGPL-3.0-or-later + ORC + CC-BY-SA 4.0)

See LICENSE, LICENSE-ORC, and LICENSE-CC-BY-SA at repository root.