# Interfaces & Protocols

> **Protocol-driven architecture**: hive-mcp defines all system boundaries as Clojure `defprotocol` interfaces. Implementations live in separate packages, enabling the [Open Protocols / Closed Implementations](#architecture-open-protocols--closed-implementations) pattern.

**Total protocols: ~49** | **Core (protocols/ dir): 20** | **Domain: ~29**

---

## Table of Contents

- [Core Protocols](#core-protocols)
  - [Knowledge Graph (KG)](#knowledge-graph-kg)
  - [Memory](#memory)
  - [Workflow](#workflow) :new: 0.12.0
  - [Channel](#channel)
  - [Agent Bridge](#agent-bridge) :new: 0.12.0
  - [Connectors](#connectors)
  - [Automation](#automation)
  - [Dispatch](#dispatch)
- [Domain Protocols](#domain-protocols)
  - [Agent Lifecycle](#agent-lifecycle)
  - [Ling Strategy](#ling-strategy) :new: 0.12.0
  - [Agora (Coordination)](#agora-coordination)
  - [Swarm Registry](#swarm-registry)
  - [Graph Store](#graph-store)
  - [Infrastructure](#infrastructure)
- [New in 0.12.0](#new-in-0120)
- [Architecture: Open Protocols / Closed Implementations](#architecture-open-protocols--closed-implementations)
- [Design Patterns](#design-patterns)

---

## Core Protocols

All core protocols live in `src/hive_mcp/protocols/` and follow Interface Segregation (SOLID-I).

### Knowledge Graph (KG)

> `src/hive_mcp/protocols/kg.clj` | License: AGPL-3.0

Abstracts Datalog store backends for the Knowledge Graph.

#### IKGStore

Core graph operations for KG storage backends.

| Method | Signature | Description |
|--------|-----------|-------------|
| `ensure-conn!` | `[this]` | Initialize connection (idempotent, thread-safe) |
| `transact!` | `[this tx-data]` | Transact data, returns `{:db-before :db-after :tx-data}` |
| `query` | `[this q]` `[this q inputs]` | Execute Datalog query, returns set of tuples |
| `entity` | `[this eid]` | Get entity by ID, returns map or nil |
| `entid` | `[this lookup-ref]` | Resolve lookup ref (e.g. `[:kg-edge/id "x"]`) to entity ID |
| `pull-entity` | `[this pattern eid]` | Pull entity with pattern (e.g. `'[*]'`) |
| `db-snapshot` | `[this]` | Get immutable DB value for querying |
| `reset-conn!` | `[this]` | Reset to fresh/empty database |
| `close!` | `[this]` | Close connection, release resources |

**Implementations**: DataScriptStore (in-memory, default), DatalevinStore (persistent/LMDB), DatahikeStore (temporal)

**Noop**: `NoopKGStore` - writes silently dropped, queries return `#{}`, lookups return `nil`

#### ITemporalKGStore

Optional extension for time-travel queries (Datahike only).

| Method | Signature | Description |
|--------|-----------|-------------|
| `history-db` | `[this]` | DB with all historical facts (including retracted) |
| `as-of-db` | `[this tx-or-time]` | DB snapshot at a specific point in time |
| `since-db` | `[this tx-or-time]` | DB with facts added since a point in time |

---

### Memory

> `src/hive_mcp/protocols/memory.clj` | License: AGPL-3.0

Abstracts memory storage for persistent knowledge entries.

#### IMemoryStore

Core CRUD + semantic search for memory entries.

| Method | Signature | Description |
|--------|-----------|-------------|
| `connect!` | `[this config]` | Initialize backend connection, returns `{:success? :backend :errors}` |
| `disconnect!` | `[this]` | Close connection, release resources |
| `connected?` | `[this]` | Lightweight state check (boolean) |
| `health-check` | `[this]` | Active verification, returns `{:healthy? :latency-ms :entry-count}` |
| `add-entry!` | `[this entry]` | Add memory entry, returns entry ID |
| `get-entry` | `[this id]` | Get entry by ID, returns map or nil |
| `update-entry!` | `[this id updates]` | Partial update, auto-updates `:updated` timestamp |
| `delete-entry!` | `[this id]` | Delete entry, returns boolean |
| `query-entries` | `[this opts]` | Query with `:type`, `:tags`, `:project-id`, `:duration` filters |
| `search-similar` | `[this query-text opts]` | Semantic similarity search (vector-based) |
| `supports-semantic-search?` | `[this]` | Check if backend supports vector search |
| `cleanup-expired!` | `[this]` | Delete expired entries, returns `{:count :deleted-ids}` |
| `entries-expiring-soon` | `[this days opts]` | Entries expiring within N days |
| `find-duplicate` | `[this type content-hash opts]` | SHA-256 dedup detection |
| `store-status` | `[this]` | Backend status and config info |
| `reset-store!` | `[this]` | Reset to empty (destructive) |

**Entry shape**: `{:id :type :content :tags :duration :project-id :created :updated :content-hash :abstraction-level :staleness-alpha :staleness-beta ...}`

**Implementations**: ChromaStore (vector DB, production), DataScriptStore (in-memory, testing), AtomStore (minimal)

#### IMemoryStoreWithAnalytics

Optional extension for usage tracking.

| Method | Signature | Description |
|--------|-----------|-------------|
| `log-access!` | `[this id]` | Increment `:access-count` for entry |
| `record-feedback!` | `[this id feedback]` | Record `:helpful` or `:unhelpful` feedback |
| `get-helpfulness-ratio` | `[this id]` | Calculate helpfulness ratio (0.0-1.0) |

#### IMemoryStoreWithStaleness

Optional extension for Bayesian freshness tracking.

| Method | Signature | Description |
|--------|-----------|-------------|
| `update-staleness!` | `[this id staleness-opts]` | Update Bayesian Alpha/Beta parameters |
| `get-stale-entries` | `[this threshold opts]` | Entries above staleness probability threshold |
| `propagate-staleness!` | `[this source-id depth]` | Transitive staleness propagation |

---

### Workflow

> `src/hive_mcp/protocols/workflow.clj` | License: AGPL-3.0 | **:new: NEW in 0.12.0**

Workflow engine protocol for multi-step process execution. Backed by `hive.events.fsm` (EDN-defined FSM workflow specs compiled via SCI).

#### IWorkflowEngine

| Method | Signature | Description |
|--------|-----------|-------------|
| `load-workflow` | `[this workflow-name opts]` | Load workflow def by name, returns `{:workflow-id :steps :loaded?}` |
| `validate-workflow` | `[this workflow]` | Validate DAG (no cycles), returns `{:valid? :dependency-order}` |
| `execute-step` | `[this workflow step-id opts]` | Execute single step, returns `{:success? :result :context}` |
| `execute-workflow` | `[this workflow opts]` | Execute all steps in topological order |
| `get-status` | `[this workflow-id]` | Query execution status (`:pending` `:running` `:completed` `:failed` `:cancelled`) |
| `cancel-workflow` | `[this workflow-id opts]` | Cancel with optional cleanup hooks |

**Implementations**: FSMWorkflowEngine (EDN specs + SCI compilation), NoopWorkflowEngine (fallback)

#### IWorkflowPersistence

Optional extension for durable workflow state.

| Method | Signature | Description |
|--------|-----------|-------------|
| `save-state` | `[this workflow-id state]` | Persist execution state |
| `load-state` | `[this workflow-id]` | Load persisted state |
| `list-workflows` | `[this opts]` | List workflow executions |

---

### Channel

> `src/hive_mcp/protocols/channel.clj` | License: AGPL-3.0

Messaging abstractions for agent coordination and event distribution.

#### IChannel

Core pub/sub messaging (14 methods).

| Method | Signature | Description |
|--------|-----------|-------------|
| `channel-id` | `[this]` | Unique identifier for this channel |
| `channel-info` | `[this]` | Metadata including `:type`, `:capabilities` |
| `send!` | `[this topic payload]` `[this topic payload opts]` | Send message to topic |
| `send-async!` | `[this topic payload opts]` | Fire-and-forget send |
| `broadcast!` | `[this payload opts]` | Send to all subscribers |
| `receive!` | `[this topic]` `[this topic opts]` | Blocking receive |
| `receive-batch!` | `[this topic opts]` | Batch receive |
| `subscribe!` | `[this topic handler]` `[this topic handler opts]` | Subscribe with handler (wildcards supported) |
| `unsubscribe!` | `[this subscription-id]` | Remove subscription |
| `subscriptions` | `[this]` | List active subscriptions |
| `open?` | `[this]` | Check if channel is operational |
| `close!` | `[this]` | Close channel, release resources |
| `drain!` | `[this opts]` | Graceful drain before close |
| `channel-status` | `[this]` | Comprehensive status + metrics |

**Implementations**: AsyncChannel (core.async), RedisChannel, MqttChannel, WebSocketChannel, NoopChannel

#### IChannelWithAck

Optional: reliable delivery with acknowledgment.

| Method | Signature | Description |
|--------|-----------|-------------|
| `ack!` | `[this message-id]` | Acknowledge message processing |
| `nack!` | `[this message-id opts]` | Negative ack with optional requeue |
| `pending-acks` | `[this]` | Messages awaiting acknowledgment |

#### IChannelWithReplay

Optional: message replay for event sourcing.

| Method | Signature | Description |
|--------|-----------|-------------|
| `replay!` | `[this topic opts]` | Replay historical messages with handler |
| `history` | `[this topic opts]` | Query message history without handlers |

#### IVoice

Voice/call communication for agent coordination.

| Method | Signature | Description |
|--------|-----------|-------------|
| `voice-id` | `[this]` | Unique voice instance identifier |
| `start-call` | `[this participants opts]` | Initiate voice call |
| `end-call` | `[this call-id]` | End active call |
| `mute` | `[this call-id]` | Mute local audio |
| `unmute` | `[this call-id]` | Unmute local audio |
| `call-status` | `[this call-id]` | Query call status |

**Implementations**: WebRTCVoice, SIPVoice, NoopVoice

#### IRouter

Message routing dispatch layer above individual channels.

| Method | Signature | Description |
|--------|-----------|-------------|
| `router-id` | `[this]` | Unique router identifier |
| `router-info` | `[this]` | Router metadata + strategy |
| `route-message` | `[this topic payload opts]` | Route to appropriate channel(s) |
| `register-route!` | `[this channel-id channel opts]` | Register channel with topic patterns |
| `unregister-route!` | `[this channel-id]` | Remove channel from router |
| `router-channels` | `[this]` | List registered channels |
| `resolve-route` | `[this topic]` | Preview routing without sending |

**Implementations**: TopicRouter, RoundRobinRouter, PriorityRouter, NoopRouter

---

### Agent Bridge

> `src/hive_mcp/protocols/agent_bridge.clj` | License: AGPL-3.0 | **:new: NEW in 0.12.0**

Backend-agnostic abstractions for programmatic agent interaction. Enables hive-mcp to control external agent SDKs (Claude Agent SDK, OpenAI, etc.) through a unified interface.

#### IAgentSession

Session interaction cycle (query/interrupt/stream).

| Method | Signature | Description |
|--------|-----------|-------------|
| `session-id` | `[this]` | Unique session identifier |
| `query!` | `[this prompt opts]` | Send prompt, returns core.async channel of responses |
| `interrupt!` | `[this]` | Interrupt current query |
| `receive-messages` | `[this]` | core.async channel of streaming messages |
| `receive-response` | `[this]` | core.async channel yielding final response |

#### IAgentBackend

Backend lifecycle management.

| Method | Signature | Description |
|--------|-----------|-------------|
| `backend-id` | `[this]` | Keyword identifier (`:noop`, `:claude-sdk`, `:openai-sdk`) |
| `available?` | `[this]` | Check if backend is ready |
| `capabilities` | `[this]` | Set of capabilities (`:streaming`, `:tools`, `:sessions`, `:saa`, etc.) |
| `execute!` | `[this task opts]` | One-shot task execution |
| `connect!` | `[this opts]` | Create and return IAgentSession |
| `disconnect!` | `[this session]` | Clean up session |

**External implementations**: ClaudeSDKBackend (libpython-clj + Claude Agent SDK)

#### IAgentTools

Custom tool registration.

| Method | Signature | Description |
|--------|-----------|-------------|
| `register-tool!` | `[this session tool-spec]` | Register Clojure fn as agent tool |
| `register-mcp-server!` | `[this session server-config]` | Register MCP server with session |
| `list-tools` | `[this session]` | List available tools |

#### IAgentPermissions

Permission control.

| Method | Signature | Description |
|--------|-----------|-------------|
| `set-permission-mode!` | `[this session mode]` | Set mode (`:default`, `:accept-edits`, `:bypass`) |
| `set-permission-handler!` | `[this session handler-fn]` | Custom per-tool permission handler |

#### ISAAOrchestrator

SAA (Silence-Abstract-Act) three-phase orchestration.

| Method | Signature | Description |
|--------|-----------|-------------|
| `run-silence!` | `[this session task opts]` | Phase 1: observe with read-only tools |
| `run-abstract!` | `[this session observations opts]` | Phase 2: synthesize observations into plan |
| `run-act!` | `[this session plan opts]` | Phase 3: execute plan with full tool access |
| `run-full-saa!` | `[this session task opts]` | Complete SAA cycle |

**Noop**: `NoopAgentBackend` implements IAgentBackend + IAgentTools + IAgentPermissions + ISAAOrchestrator

---

### Connectors

> `src/hive_mcp/protocols/connector.clj` | License: AGPL-3.0

External system integration abstractions.

#### IConnector

Connection lifecycle for APIs, brokers, IoT, webhooks.

| Method | Signature | Description |
|--------|-----------|-------------|
| `connector-id` | `[this]` | Unique keyword identifier |
| `connector-info` | `[this]` | Metadata + `:system-type` + `:capabilities` |
| `connect!` | `[this opts]` | Establish connection with credentials/endpoint |
| `disconnect!` | `[this]` | Close connection |
| `connected?` | `[this]` | Lightweight state check |
| `health-check` | `[this]` | Active health verification |
| `reconnect!` | `[this opts]` | Re-establish lost connection |
| `get-status` | `[this]` | Comprehensive status + metrics |
| `send` | `[this data opts]` | Send data to external system |
| `receive` | `[this opts]` | Pull data from external system |
| `sync!` | `[this opts]` | Bidirectional synchronization |

**Noop**: `NoopConnector`

#### IDataMapper

Bidirectional data transformation (external <-> hive internal).

| Method | Signature | Description |
|--------|-----------|-------------|
| `mapper-id` | `[this]` | Unique keyword identifier |
| `mapper-info` | `[this]` | Metadata + `:source-type` + `:target-type` |
| `inbound` | `[this external-data opts]` | External -> hive-mcp format |
| `outbound` | `[this internal-data opts]` | Hive-mcp -> external format |
| `validate-inbound` | `[this external-data]` | Lightweight validation pre-transform |
| `supported-formats` | `[this]` | Set of supported formats |

**Default**: `IdentityMapper` (passthrough, auto-registered)

#### IAuthProvider

Token-based authentication lifecycle.

| Method | Signature | Description |
|--------|-----------|-------------|
| `authenticate` | `[this credentials]` | Obtain token from credentials |
| `refresh-token` | `[this token]` | Renew expired token |
| `valid?` | `[this token]` | Check token validity |

**Noop**: `NoopAuthProvider` (always succeeds, mock tokens)

---

### Automation

> `src/hive_mcp/protocols/automation.clj` | License: AGPL-3.0

Browser automation and web scraping abstractions.

#### IAutomationSession

Session identity and lifecycle.

| Method | Signature | Description |
|--------|-----------|-------------|
| `session-id` | `[this]` | Unique session identifier |
| `session-info` | `[this]` | Metadata (browser, headless?, viewport) |
| `active?` | `[this]` | Check if session is usable |

#### IBrowserAutomation

Core browser control operations.

| Method | Signature | Description |
|--------|-----------|-------------|
| `launch!` | `[this opts]` | Launch browser, create session |
| `close!` | `[this]` | Close browser, release resources |
| `navigate!` | `[this url opts]` | Navigate to URL |
| `click!` | `[this selector opts]` | Click element by CSS/XPath selector |
| `type-text!` | `[this selector text opts]` | Type into input element |
| `screenshot!` | `[this opts]` | Capture page screenshot |
| `get-page-source` | `[this]` | Get page HTML source |
| `wait-for-selector` | `[this selector opts]` | Wait for element to appear |
| `evaluate-js` | `[this expression opts]` | Execute JavaScript in browser context |

**Future implementations**: PlaywrightAutomation, PuppeteerAutomation

**Noop**: `NoopBrowserAutomation`, `NoopAutomationSession`

---

### Dispatch

> `src/hive_mcp/protocols/dispatch.clj` | License: AGPL-3.0

Polymorphic dispatch context for agent communication.

#### IDispatchContext

| Method | Signature | Description |
|--------|-----------|-------------|
| `resolve-context` | `[this]` | Returns consumable map `{:prompt <string>}` + optional `:refs`, `:kg-nodes` |
| `context-type` | `[this]` | Returns `:text`, `:ref`, or `:graph-ref` |

**Records**:

| Record | Type | Description |
|--------|------|-------------|
| `TextContext` | `:text` | Plain text prompt (backward compatible) |
| `RefContext` | `:ref` | Pass-by-reference context (~25x smaller than text) |
| `GraphContext` | `:graph-ref` | Graph-native traversal (degrades to TextContext if backend unavailable) |

**Factory functions**: `->text-context`, `->ref-context`, `->graph-context`, `ensure-context`

---

## Domain Protocols

Protocols outside `protocols/` dir, co-located with their domain modules.

### Agent Lifecycle

> `src/hive_mcp/agent/protocol.clj` | License: AGPL-3.0

#### IAgent

Core agent lifecycle (10 methods).

| Method | Signature | Description |
|--------|-----------|-------------|
| `spawn!` | `[this opts]` | Spawn agent instance |
| `dispatch!` | `[this task opts]` | Send task to agent |
| `kill!` | `[this opts]` | Terminate agent |
| `status` | `[this]` | Get agent status |
| `agent-type` | `[this]` | Return type keyword (`:ling`) |
| `can-chain-tools?` | `[this]` | Whether agent supports tool chaining |
| `claims` | `[this]` | Get file ownership claims |
| `claim-files!` | `[this files]` | Claim file ownership |
| `release-claims!` | `[this]` | Release all file claims |
| `upgrade!` | `[this new-opts]` | Upgrade agent configuration |

#### IAgentRegistry

Agent registry operations.

| Method | Signature | Description |
|--------|-----------|-------------|
| `register!` | `[this agent]` | Register agent |
| `unregister!` | `[this agent-id]` | Unregister agent |
| `get-agent` | `[this agent-id]` | Get agent by ID |
| `list-agents` | `[this]` | List all agents |
| `list-agents-by-type` | `[this type]` | Filter agents by type |

#### LLMBackend

LLM model abstraction.

| Method | Signature | Description |
|--------|-----------|-------------|
| `chat` | `[this messages opts]` | Send chat messages |
| `model-name` | `[this]` | Return model identifier |

---

### Ling Strategy

> `src/hive_mcp/agent/ling/strategy.clj` | License: AGPL-3.0 | **:new: NEW in 0.12.0**

Strategy pattern for mode-specific ling spawn/dispatch operations. The `Ling` record delegates mode-specific calls to its strategy, keeping mode-independent operations (claims, agent-type) on the record itself.

#### ILingStrategy

| Method | Signature | Description |
|--------|-----------|-------------|
| `strategy-spawn!` | `[this ling-ctx opts]` | Spawn using strategy's mechanism |
| `strategy-dispatch!` | `[this ling-ctx task-opts]` | Dispatch task to running ling |
| `strategy-status` | `[this ling-ctx ds-status]` | Get mode-specific status |
| `strategy-kill!` | `[this ling-ctx]` | Terminate via strategy's mechanism |

**Implementations**: VtermStrategy (Emacs buffer), HeadlessStrategy (ProcessBuilder subprocess), AgentSDKStrategy (Claude Agent SDK)

---

### Agora (Coordination)

> `src/hive_mcp/agora/protocol.clj` | License: AGPL-3.0

Multi-agent dialogue and consensus protocols.

#### ICoordination

| Method | Signature | Description |
|--------|-----------|-------------|
| `add-participant` | `[this participant]` | Add agent to dialogue |
| `remove-participant` | `[this participant-id]` | Remove agent |
| `get-participants` | `[this]` | List participants |
| `signal` | `[this participant-id signal]` | Send coordination signal |
| `check-consensus` | `[this]` | Check Nash equilibrium |
| `next-turn` | `[this]` | Get next turn |
| `get-turns` | `[this]` | Get turn history |
| `get-id` | `[this]` | Dialogue identifier |

**Implementations**: DialogueCoordination

#### ISignalable

| Method | Signature | Description |
|--------|-----------|-------------|
| `emit` | `[this event]` | Emit event |
| `subscribe` | `[this handler]` | Subscribe to events |

#### IConsensus

| Method | Signature | Description |
|--------|-----------|-------------|
| `threshold` | `[this]` | Get consensus threshold |
| `evaluate` | `[this signals]` | Evaluate if consensus reached |


---

### Swarm Registry

> `src/hive_mcp/swarm/protocol.clj` | License: AGPL-3.0

#### ISwarmRegistry

DataScript-backed swarm state management.

| Method | Signature | Description |
|--------|-----------|-------------|
| `add-slave!` | `[this slave-data]` | Register agent |
| `get-slave` | `[this slave-id]` | Get agent record |
| `update-slave!` | `[this slave-id updates]` | Update agent state |
| `remove-slave!` | `[this slave-id]` | Unregister agent |
| `get-all-slaves` | `[this]` | List all agents |
| `get-slaves-by-status` | `[this status]` | Filter by status |
| `get-slaves-by-project` | `[this project-id]` | Filter by project |
| `add-task!` | `[this task-data]` | Add task record |
| `get-task` | `[this task-id]` | Get task record |
| `update-task!` | `[this task-id updates]` | Update task state |
| `get-tasks-for-slave` | `[this slave-id]` | Get agent's tasks |

---

### Graph Store

> `src/hive_mcp/graph/protocol.clj` | License: AGPL-3.0

#### GraphStore

Legacy KG interface (predates IKGStore).

| Method | Signature | Description |
|--------|-----------|-------------|
| `transact!` | `[this tx-data]` | Transact data |
| `query` | `[this q]` `[this q inputs]` | Execute query |
| `entity` | `[this eid]` | Get entity |
| `find-similar` | `[this entry opts]` | Similarity search |
| `history` | `[this entry-id]` | Entry history |
| `persist!` | `[this path]` | Persist to file |
| `restore!` | `[this path]` | Restore from file |

---

### Infrastructure

Additional protocols scattered across the codebase:

| Protocol | File | Methods | Purpose |
|----------|------|---------|---------|
| `EmbeddingProvider` | `chroma.clj` | `embed-text`, `embed-batch`, `embedding-dimension` | Vector embedding generation |
| `ITransport` | `transport.clj` | `connect!`, `disconnect!`, `connected?`, `send!`, `recv!`, `get-stream` | Low-level transport |
| `IServer` | `transport.clj` | `stop-server!`, `server-running?`, `get-clients` | Server management |
| `IAddon` | `addons/core.clj` | `addon-name`, `addon-version`, `addon-info`, `init!`, `shutdown!`, `addon-tools`, `addon-capabilities` | Plugin system |
| `ITDDParticipant` | `tdd/protocol.clj` | `participant-id`, `participant-type`, `execute-task!`, `get-preset` | TDD workflow roles |
| `IAdapter` | `migration/adapter.clj` | `adapter-id`, `adapter-info`, `export-transform`, `import-transform`, `validate-external` | Migration adapters |
| `CircuitBreaker` | `resilience.clj` | — | Resilience pattern |
| `IEmacsDaemon` | `emacs/daemon.clj` | — | Multi-daemon management |
| `PromptStore` | `prompt/storage.clj` | — | Prompt template storage |
| `ReplEvaluator` | `evaluator.clj` | — | REPL evaluation abstraction |
| `DiagramAdapter` | `diagrams/core.clj` | — | Diagram rendering |
| `KanbanRenderer` | `org_clj/render.clj` | — | Kanban → Org-mode rendering |

---

## New in 0.12.0

Release 0.12.0 introduces several new protocols and implementations:

### New Protocols

| Protocol | Domain | Purpose |
|----------|--------|---------|
| **IWorkflowEngine** | Workflow | Multi-step workflow execution with FSM backing |
| **IWorkflowPersistence** | Workflow | Durable workflow state for resume/audit |
| **IAgentSession** | Agent Bridge | Streaming agent session interaction |
| **IAgentBackend** | Agent Bridge | Backend-agnostic agent lifecycle |
| **IAgentTools** | Agent Bridge | Custom tool registration with agents |
| **IAgentPermissions** | Agent Bridge | Permission mode/handler configuration |
| **ISAAOrchestrator** | Agent Bridge | Silence-Abstract-Act phase orchestration |
| **ILingStrategy** | Agent | Strategy pattern for ling spawn modes |

### New Implementations

| Implementation | Protocol | Description |
|----------------|----------|-------------|
| **FSMWorkflowEngine** | IWorkflowEngine | EDN FSM specs compiled via SCI |
| **VtermStrategy** | ILingStrategy | Emacs vterm buffer spawn |
| **HeadlessStrategy** | ILingStrategy | ProcessBuilder subprocess spawn |
| **AgentSDKStrategy** | ILingStrategy | Claude Agent SDK spawn via libpython-clj |
| **ClaudeSDKBackend** | IAgentBackend | Claude Agent SDK bridge (external) |
| **NoopAgentBackend** | IAgentBackend | No-op fallback (implements 4 protocols) |
| **NoopWorkflowEngine** | IWorkflowEngine | No-op fallback |

### New Records

| Record | Protocol | Description |
|--------|----------|-------------|
| **TextContext** | IDispatchContext | Plain text dispatch (backward compat) |
| **RefContext** | IDispatchContext | Pass-by-reference context (~25x savings) |

---

## Architecture: Open Protocols / Closed Implementations

hive-mcp follows a strict **open protocol / closed implementation** pattern that maps to its licensing boundary:

```
┌─────────────────────────────────────────────────────────────────┐
│  OPEN (AGPL-3.0) — hive-mcp                                    │
│                                                                 │
│  defprotocol IKGStore        defprotocol IMemoryStore          │
│  defprotocol IWorkflowEngine defprotocol IChannel              │
│  defprotocol IAgentBackend   defprotocol IConnector            │
│                                                                 │
│  DataScriptStore (testing)   NoopChannel                       │
│  NoopWorkflowEngine          NoopConnector                     │
│  NoopAgentBackend                                              │
│                                                                 │
├─────────────────────────── requiring-resolve ────────────────────┤
│                                                                 │
│  ADDONS — separate repos, loaded via classpath discovery        │
│                                                                 │
│  DatalevinStore (production)  ClaudeSDKBackend                  │
│  DistributedWorkflowEngine   lsp-mcp, scc-mcp, clj-kondo-mcp  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Key Principles

1. **Protocols are always AGPL**: Every `defprotocol` is in `hive-mcp` and fully open
2. **Noop fallbacks everywhere**: hive-mcp works standalone with NoopWorkflowEngine, NoopChannel, etc.
3. **`requiring-resolve` stub pattern**: Enhanced implementations are loaded at runtime via `requiring-resolve`, falling back to noop if not on classpath
4. **No compile-time coupling**: hive-mcp never `(:require ...)` proprietary namespaces

### Implementing a Protocol

To implement any hive-mcp protocol:

```clojure
;; 1. Require the protocol
(require '[hive-mcp.protocols.kg :as kg])

;; 2. Implement with defrecord
(defrecord MyKGStore [conn-atom]
  kg/IKGStore
  (ensure-conn! [this] ...)
  (transact! [this tx-data] ...)
  (query [this q] ...)
  (query [this q inputs] ...)
  (entity [this eid] ...)
  (entid [this lookup-ref] ...)
  (pull-entity [this pattern eid] ...)
  (db-snapshot [this] ...)
  (reset-conn! [this] ...)
  (close! [this] ...))

;; 3. Register at init time
(kg/set-store! (->MyKGStore (atom nil)))
```

### Active Atom Management Pattern

Every core protocol follows the same lifecycle pattern:

```clojure
(defonce ^:private active-store (atom nil))

(defn set-store! [store]      ;; Set during initialization
  {:pre [(satisfies? IKGStore store)]}
  (reset! active-store store))

(defn get-store []             ;; Get with error if unset
  (or @active-store (throw ...)))

(defn store-set? []            ;; Check if configured
  (some? @active-store))

(defn clear-store! []          ;; Reset (testing)
  (when-let [s @active-store]
    (close! s))
  (reset! active-store nil))
```

---

## Design Patterns

### Pattern: Interface Segregation (SOLID-I)

Protocols are small and focused. Example from Agent Bridge:

```
IAgentSession      — Session interaction (query, interrupt, stream)
IAgentBackend      — Backend lifecycle (connect, disconnect, capabilities)
IAgentTools        — Tool registration
IAgentPermissions  — Permission control
ISAAOrchestrator   — SAA phase orchestration
```

A backend can implement all 5, or just IAgentBackend. NoopAgentBackend implements all 5 in one record.

### Pattern: Noop Fallback

Every protocol has a no-op implementation that ensures the system runs without real backends:

| Protocol | Noop Record | Behavior |
|----------|-------------|----------|
| IKGStore | NoopKGStore | Queries return `#{}` |
| IMemoryStore | (none, uses AtomStore) | In-memory only |
| IWorkflowEngine | NoopWorkflowEngine | Returns `:loaded? false` |
| IChannel | NoopChannel | Sends succeed silently |
| IBrowserAutomation | NoopBrowserAutomation | Returns `:success? false` |
| IAgentBackend | NoopAgentBackend | Returns empty capabilities |
| IConnector | NoopConnector | Mock send/receive |

### Pattern: CLARITY-Y (Yield Safe Failure)

Methods never throw exceptions. They return result maps:

```clojure
{:success? false
 :errors ["NoopWorkflowEngine: No workflow engine configured."]
 :result nil}
```

This makes error handling uniform and composable across the entire system.

### Pattern: Registry + Active Atom

Large protocol families (Channel, Connector, Automation) use dual management:
- **Registry**: Multiple instances, keyed by ID (e.g. `:redis-channel`, `:mqtt-channel`)
- **Active Atom**: Single "currently active" instance for convenience

---

*Last updated: 2026-02-07 | Release: 0.12.0*