# Hub Core Library

## Purpose

Hub-core is a standalone library extracted from substrate that provides the foundational infrastructure for building hub-based systems. It contains the core routing, plugin architecture, and MCP integration without any application-specific activations.

## Architecture

### Core Components

```
hub-core/
├── plexus/           # Central routing and dispatch
│   ├── plexus.rs     # Plexus struct, method routing
│   ├── activation.rs # Activation trait definition
│   ├── schema.rs     # Schema generation and introspection
│   ├── streaming.rs  # Stream wrapping utilities
│   └── error.rs      # PlexusError types
├── mcp_bridge.rs     # PlexusMcpBridge for MCP server integration
├── types/            # Core types
│   ├── handle.rs     # Handle<T> typed references
│   ├── envelope.rs   # Envelope wrapper with metadata
│   └── origin.rs     # Origin tracking for method calls
├── plugin_system.rs  # Plugin registration infrastructure
└── activations/      # Example activations
    ├── echo.rs       # Simple echo activation (hub-macro example)
    └── health.rs     # Health check activation (manual impl example)
```

### Key Abstractions

**Plexus**: Central router that registers activations and dispatches method calls. Provides:
- Method routing via `namespace.method` convention
- Schema introspection with recursive hashing
- Handle resolution across plugins

**Activation**: Trait that plugins implement to expose methods:
```rust
pub trait Activation: Send + Sync {
    fn namespace(&self) -> &'static str;
    fn plugin_id(&self) -> Uuid;
    fn schema(&self) -> PluginSchema;
    fn call(&self, method: &str, params: Value) -> BoxFuture<'_, Result<Value, PlexusError>>;
    fn resolve_handle(&self, handle: &Handle<Value>) -> Option<BoxFuture<'_, Result<Value, PlexusError>>>;
}
```

**PlexusMcpBridge**: Adapter that exposes a Plexus as an MCP server via rmcp, enabling Claude Code and other MCP clients to call hub methods as tools.

**Handle<T>**: Typed reference to a method result, containing plugin_id, method, and optional metadata. Enables cross-plugin references and lazy resolution.

## Design Decisions

### Why Extract to Library

1. **Reusability**: Other projects need hub infrastructure without substrate's activations
2. **Clean Dependencies**: Substrate activations pull in heavy deps (sqlx, cllient, etc.)
3. **Clear Boundaries**: Separates infrastructure from application logic
4. **Testing**: Easier to test core infrastructure in isolation

### What's Included vs Excluded

**Included** (infrastructure):
- Plexus routing and registration
- Activation trait and schema generation
- MCP bridge integration
- Handle/Envelope/Origin types
- Echo and Health as minimal examples

**Excluded** (application-specific):
- Arbor (tree storage)
- Bash (shell execution)
- Changelog (version tracking)
- ClaudeCode (Claude Code sessions)
- Cone (LLM agents)
- Mustache (templating)
- Solar (demo celestial bodies)

### Example Activations

Two examples demonstrate different approaches:

1. **Echo** - Uses `#[hub_activation]` macro for declarative method definition
2. **Health** - Manual `Activation` impl showing what the macro generates

## Usage

```rust
use hub_core::{Plexus, Activation, PlexusMcpBridge};
use hub_core::activations::{Echo, Health};

// Build a plexus with activations
let plexus = Arc::new(
    Plexus::new()
        .register(Health::new())
        .register(Echo::new())
        .register(MyCustomActivation::new())
);

// Use as MCP server
let bridge = PlexusMcpBridge::new(plexus);
// ... run with rmcp transport

// Or call directly
let result = plexus.call("echo.echo", json!({"message": "hello", "count": 3})).await?;
```

## Relationship to hub-macro

Hub-core depends on `hub-macro` for the `#[hub_activation]` procedural macro. The macro generates:
- `Activation` trait implementation
- Method dispatch logic
- Schema generation from method signatures
- Streaming support for async iterators

Projects using hub-core can either:
1. Use `#[hub_activation]` macro (recommended)
2. Implement `Activation` manually (for special cases)

## Future Considerations

- Consider publishing to crates.io once stable
- May need versioning strategy for schema compatibility
- Could add more example activations for common patterns
