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       ?
??????????????????????????????????????????????????????????

Invariant	Monolithic Plugin Pattern	Harbormaster KPP Adapter Layer
Transport Model	Shared process memory / DLL loading	Strict IPv4 loopback HTTP (`127.0.0.1:8765`)
Protocol Wire Format	Language-specific C-ABI or FFI	Spec-compliant JSON-RPC 2.0
Privilege Ceiling	Ambient filesystem & process authority	Scoped capability tokens granted by operator
Failure Domain	Plugin crash terminates core engine	Isolated process crash; engine remains healthy
Network Exposure	Varies by plugin implementation	Hard-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":{}}'