# 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](execution.md) | ✅ 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](config.md) | ✅ Production | Configuration management | 80+ env vars, dynamic assignments, SIGHUP reload, role definitions |
| [pkg/bootstrap](bootstrap.md) | ✅ Production | System bootstrapping | Initialization sequences, dependency ordering |

---

## Distributed Infrastructure

### P2P Networking

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

### Coordination & Election

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

### SLURP System

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

---

## Security & Validation

### Cryptography

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

### Validation & Compliance

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

---

## AI & Intelligence

### AI Providers

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

### Protocols

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

---

## Observability

### Monitoring

| Package | Status | Purpose | Key Features |
|---------|--------|---------|--------------|
| [pkg/metrics](metrics.md) | ✅ Production | Metrics collection | 80+ Prometheus metrics, custom collectors, histograms |
| [pkg/health](health.md) | ✅ 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](storage.md) | ✅ Production | Storage abstractions | Key-value interface, backends, caching |
| [pkg/repository](repository.md) | ✅ Production | Git operations | Clone, commit, push, branch management, credential handling |

### Utilities

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

### Web & API

| Package | Status | Purpose | Key Features |
|---------|--------|---------|--------------|
| [pkg/web](web.md) | ✅ Production | Web server utilities | Static file serving, middleware, routing helpers |
| [pkg/protocol](protocol.md) | ✅ Production | Protocol definitions | Message formats, RPC protocols, serialization |
| [pkg/integration](integration.md) | ✅ 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](execution.md) - Sandboxed execution
2. [pkg/config](config.md) - Configuration
3. [coordinator/](coordinator.md) - Task routing
4. [pkg/metrics](metrics.md) - Monitoring

### Setting Up P2P Networking
1. [p2p/](p2p.md) - libp2p setup
2. [discovery/](discovery.md) - Peer discovery
3. [pubsub/](pubsub.md) - Messaging
4. [pkg/dht](dht.md) - Distributed storage

### Implementing Security
1. [pkg/crypto](crypto.md) - Encryption
2. [pkg/shhh](shhh.md) - Secrets detection
3. [pkg/security](security.md) - Policy enforcement
4. [pkg/ucxl](ucxl.md) - Decision validation

### Integrating AI
1. [pkg/ai](ai.md) - Provider interface
2. [pkg/providers](providers.md) - Implementations
3. [reasoning/](reasoning.md) - Reasoning engine
4. [pkg/prompt](prompt.md) - Prompt management

### Health & Monitoring
1. [pkg/health](health.md) - Health checks
2. [pkg/metrics](metrics.md) - Metrics collection
3. [internal/backbeat](../internal/backbeat.md) - 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](../architecture/README.md) - System-wide architecture
- [Commands Documentation](../commands/README.md) - CLI tools
- [Internal Packages](../internal/README.md) - Private implementations
- [API Documentation](../api/README.md) - HTTP API reference
- [Deployment Guide](../deployment/README.md) - Production deployment

---

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