Stax Digital Garden

HBM-1001 - The Minimalist Module Adapter and Loopback Protocol

3 min read

Living Document Notice
Published 2026-09-10. The evolving architecture and revisions for this dispatch live in the Stax Digital Garden.

The Minimalist Module Adapter and Loopback Protocol

The Minimalist Module Adapter and Loopback Protocol: Monochromatic ice blue phosphor P7 vector CRT macro showing star-topology loopback orchestration hub and protocol bus matrix

Coupling personal knowledge management engines to specialized desktop clients and status extensions creates fragile, tightly bound monolithic binaries. When desktop extensions directly mutate underlying storage engines or require ambient administrative filesystem access, runtime panics and state corruption threaten the entire knowledge graph.

Harbormaster serves as the universal module-to-engine API adapter and plug layer. Operating over a local IPv4 loopback socket (127.0.0.1:8765), Harbormaster exposes the Knowledge Provider Protocol (KPP) using JSON-RPC 2.0 semantics. This architecture provides capability-negotiated access for native modules while maintaining strict operational isolation from internal engine storage routines.

The Knowledge Provider Protocol (KPP) Architecture

Local modules communicate with the Harbor knowledge engine exclusively across the loopback boundary. Harbormaster acts as an unprivileged protocol gatekeeper:

┌────────────────────────┐      ┌────────────────────────┐
│ Desktop Status Module  │      │ CLI Inspection Tool    │
└───────────┬────────────┘      └───────────┬────────────┘
            │ Ed25519 Signed Handshake      │ Capability Token
            ▼                               ▼
══════════════════════════════════════════════════════════════
       Harbormaster Loopback Listener (127.0.0.1:8765)
══════════════════════════════════════════════════════════════
            │ Validated JSON-RPC 2.0 Calls
            ▼
┌────────────────────────────────────────────────────────┐
│               Harbor Knowledge Engine                  │
│       - Relational Graph & Note Query Engine           │
│       - Strictly Read-Only Introspection Adapter       │
└────────────────────────────────────────────────────────┘
InvariantMonolithic Plugin PatternHarbormaster KPP Adapter Layer
Transport ModelShared process memory / DLL loadingStrict IPv4 loopback HTTP (127.0.0.1:8765)
Protocol Wire FormatLanguage-specific C-ABI or FFISpec-compliant JSON-RPC 2.0
Privilege CeilingAmbient filesystem & process authorityScoped capability tokens granted by operator
Failure DomainPlugin crash terminates core engineIsolated process crash; engine remains healthy
Network ExposureVaries by plugin implementationHard-coded deny on non-loopback interfaces

JSON-RPC 2.0 Method Invocation Contract

Modules query engine state using typed JSON-RPC requests. The handler validates capability tokens before dispatching calls to internal engine adapters.

interface JsonRpcRequest {
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params: Record<string, unknown>;
}
 
interface JsonRpcResponse<T = unknown> {
  jsonrpc: "2.0";
  id: string | number;
  result?: T;
  error?: {
    code: number;
    message: string;
    data?: unknown;
  };
}
 
// Example: Querying note graph topology over loopback
const queryGraphPayload: JsonRpcRequest = {
  jsonrpc: "2.0",
  id: "req-001",
  method: "kpp.graph.queryNeighbors",
  params: {
    noteId: "note-2026-09-10-alpha",
    depth: 1,
    includeBacklinks: true
  }
};

Local Loopback Socket Validation

Harbormaster binds exclusively to literal IPv4 127.0.0.1, rejecting IPv6, wildcard bindings, and external hostname aliases to prevent DNS rebinding attacks.

# Verify listener binds strictly to IPv4 loopback
ss -tlpn | grep 8765
 
# Probe health endpoint using literal loopback IP
curl -s -X POST http://127.0.0.1:8765/protocol/v1/rpc \
  -H "Content-Type: application/json" \
  -H "Host: 127.0.0.1:8765" \
  -d '{"jsonrpc":"2.0","id":1,"method":"kpp.system.ping","params":{}}'
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1001 - The Minimalist Module Adapter and Loopback Protocol](HBM-1001 - The Minimalist Module Adapter and Loopback Protocol)

Graph View