CHORUS/docs/comprehensive/packages/README.md

CHORUS Packages Documentation

Complete API reference for all public packages in pkg/

---

Overview

CHORUS provides 30+ public packages organized into functional categories. This index provides quick navigation to all package documentation with implementation status and key features.

---

Core System Packages

Execution & Sandboxing

Package	Status	Purpose	Key Features
pkg/execution	✅ Production	Task execution engine with Docker sandboxing	Docker Exec API, 4-tier language detection, workspace isolation, resource limits

Configuration & Runtime

Package	Status	Purpose	Key Features
pkg/config	✅ Production	Configuration management	80+ env vars, dynamic assignments, SIGHUP reload, role definitions
pkg/bootstrap	✅ Production	System bootstrapping	Initialization sequences, dependency ordering

---

Distributed Infrastructure

P2P Networking

Package	Status	Purpose	Key Features
pkg/dht	✅ Production	Distributed hash table	Kademlia DHT, encrypted storage, bootstrap, cache management
p2p/	✅ Production	libp2p networking	Host wrapper, multiaddr, connection management, DHT modes
pubsub/	✅ Production	PubSub messaging	GossipSub, 31 message types, role-based topics, HMMM integration
discovery/	✅ Production	Peer discovery	mDNS local discovery, automatic LAN detection

Coordination & Election

Package	Status	Purpose	Key Features
pkg/election	✅ Production	Leader election	Democratic election, heartbeat (5s), candidate scoring, SLURP integration
pkg/coordination	🔶 Beta	Meta-coordination	Dependency detection, AI-powered plans, cross-repo sessions
coordinator/	✅ Production	Task coordination	Task assignment, scoring, availability tracking, role-based routing

SLURP System

Package	Status	Purpose	Key Features
pkg/slurp/	🔷 Alpha	Distributed orchestration	8 subpackages, policy learning, temporal coordination
pkg/slurp/alignment	🔷 Alpha	Goal alignment	Consensus building, objective tracking
pkg/slurp/context	🔷 Alpha	Context management	Context generation, propagation, versioning
pkg/slurp/distribution	🔷 Alpha	Work distribution	Load balancing, task routing, capacity management
pkg/slurp/intelligence	🔷 Alpha	Intelligence layer	Learning, adaptation, pattern recognition
pkg/slurp/leader	🔷 Alpha	Leadership coordination	Leader management, failover, delegation
pkg/slurp/roles	🔷 Alpha	Role assignments	Dynamic roles, capability matching, hierarchy
pkg/slurp/storage	🔷 Alpha	Distributed storage	Replicated state, consistency, versioning
pkg/slurp/temporal	✅ Production	Time-based coordination	DHT integration, temporal queries, event ordering

---

Security & Validation

Cryptography

Package	Status	Purpose	Key Features
pkg/crypto	✅ Production	Encryption primitives	Age encryption, key derivation, secure random
pkg/shhh	✅ Production	Secrets management	Sentinel, pattern matching, redaction, audit logging
pkg/security	✅ Production	Security policies	Policy enforcement, validation, threat detection

Validation & Compliance

Package	Status	Purpose	Key Features
pkg/ucxl	✅ Production	UCXL validation	Decision publishing, content addressing (ucxl://), immutable audit
pkg/ucxi	🔶 Beta	UCXI server	Content resolution, address parsing, HTTP API

---

AI & Intelligence

AI Providers

Package	Status	Purpose	Key Features
pkg/ai	✅ Production	AI provider interfaces	Provider abstraction, model selection, fallback
pkg/providers	✅ Production	Concrete AI implementations	Ollama, ResetData, OpenAI-compatible
reasoning/	✅ Production	Reasoning engine	Provider switching, prompt composition, model routing
pkg/prompt	✅ Production	Prompt management	System prompts, role composition, template rendering

Protocols

Package	Status	Purpose	Key Features
pkg/mcp	🔶 Beta	Model Context Protocol	MCP server/client, tool integration, context management
pkg/hmmm	🔶 Beta	HMMM protocol	Meta-discussion, collaborative reasoning, per-issue rooms
pkg/hmmm_adapter	🔶 Beta	HMMM adapter	GossipSub bridge, room management, message routing

---

Observability

Monitoring

Package	Status	Purpose	Key Features
pkg/metrics	✅ Production	Metrics collection	80+ Prometheus metrics, custom collectors, histograms
pkg/health	✅ Production	Health monitoring	4 HTTP endpoints, 7 built-in checks, enhanced monitoring, Kubernetes probes

---

Infrastructure Support

Storage & Data

Package	Status	Purpose	Key Features
pkg/storage	✅ Production	Storage abstractions	Key-value interface, backends, caching
pkg/repository	✅ Production	Git operations	Clone, commit, push, branch management, credential handling

Utilities

Package	Status	Purpose	Key Features
pkg/types	✅ Production	Common type definitions	Shared structs, interfaces, constants across packages
pkg/agentid	✅ Production	Agent identity	ID generation, validation, uniqueness
pkg/version	✅ Production	Version information	Build info, version comparison, semantic versioning
pkg/shutdown	✅ Production	Graceful shutdown	Component ordering, timeout management, signal handling

Web & API

Package	Status	Purpose	Key Features
pkg/web	✅ Production	Web server utilities	Static file serving, middleware, routing helpers
pkg/protocol	✅ Production	Protocol definitions	Message formats, RPC protocols, serialization
pkg/integration	✅ Production	Integration utilities	External system connectors, webhooks, adapters

---

Status Legend

Symbol	Status	Meaning
✅	Production	Fully implemented, tested, production-ready
🔶	Beta	Core features complete, testing in progress
🔷	Alpha	Basic implementation, experimental
⏳	Stubbed	Interface defined, implementation incomplete
❌	Planned	Not yet implemented

---

Quick Navigation by Use Case

Building a Task Execution System

1. pkg/execution - Sandboxed execution
2. pkg/config - Configuration
3. coordinator/ - Task routing
4. pkg/metrics - Monitoring

Setting Up P2P Networking

1. p2p/ - libp2p setup
2. discovery/ - Peer discovery
3. pubsub/ - Messaging
4. pkg/dht - Distributed storage

Implementing Security

1. pkg/crypto - Encryption
2. pkg/shhh - Secrets detection
3. pkg/security - Policy enforcement
4. pkg/ucxl - Decision validation

Integrating AI

1. pkg/ai - Provider interface
2. pkg/providers - Implementations
3. reasoning/ - Reasoning engine
4. pkg/prompt - Prompt management

Health & Monitoring

1. pkg/health - Health checks
2. pkg/metrics - Metrics collection
3. internal/backbeat - P2P telemetry

---

Package Dependencies

Foundational (No Dependencies)

• pkg/types
• pkg/version
• pkg/agentid

Infrastructure Layer (Depends on Foundational)

• pkg/config
• pkg/crypto
• pkg/storage
• p2p/
• pkg/dht

Coordination Layer (Depends on Infrastructure)

• pubsub/
• pkg/election
• discovery/
• coordinator/

Application Layer (Depends on All Below)

• pkg/execution
• pkg/coordination
• pkg/slurp
• internal/runtime

---

Documentation Standards

Each package documentation includes:

1. Overview - Purpose, key capabilities, architecture
2. API Reference - All exported types, functions, constants
3. Configuration - Environment variables, config structs
4. Usage Examples - Minimum 3 practical examples
5. Implementation Status - Production/Beta/Alpha/TODO features
6. Error Handling - Error types, handling patterns
7. Testing - Test structure, running tests, coverage
8. Related Packages - Cross-references to dependencies
9. Troubleshooting - Common issues and solutions

---

Contributing to Documentation

When documenting new packages:

1. Follow the standard template structure
2. Include line numbers for code references
3. Provide runnable code examples
4. Mark implementation status clearly
5. Cross-reference related packages
6. Update this index with the new package

---

Additional Resources

• Architecture Overview - System-wide architecture
• Commands Documentation - CLI tools
• Internal Packages - Private implementations
• API Documentation - HTTP API reference
• Deployment Guide - Production deployment

---

Last Updated: 2025-09-30 Packages Documented: 22/30+ (73%) Lines Documented: ~40,000+ Examples Provided: 100+