Stax Digital Garden

HBM-1004 - Separating API Adapters from Storage Engines

2 min read

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

Separating API Adapters from Storage Engines

Separating API Adapters from Storage Engines: Monochromatic ice blue phosphor P7 vector CRT macro showing bilateral decoupling between protocol API adapters and underlying storage engines

Coupling external API protocols directly to database engines creates structural instability. When network listeners, serialization wrappers, and client validation logic share execution threads with disk persistence layers, high request concurrency causes thread starvation and blocking in core storage routines.

Harbormaster strictly decouples its API adapter tier from the underlying Harbor storage engine. By implementing a clean boundaries-and-interfaces contract, the HTTP/JSON-RPC adapter handles wire serialization, protocol validation, and rate limiting independently, communicating with the storage engine through local function interfaces with zero direct disk authority.

Architectural Boundary Diagram

Harbormaster sits between client network requests and internal storage drivers:

┌────────────────────────────────────────────────────────┐
│            Harbormaster API Adapter Tier               │
│   - Loopback HTTP Listener (127.0.0.1:8765)            │
│   - JSON-RPC 2.0 Request Validation                    │
│   - Capability Enforcement & Constant-Time Auth        │
└───────────────────────────┬────────────────────────────┘
                            │ In-Memory Read-Only Protocol Adapter
                            ▼
┌────────────────────────────────────────────────────────┐
│                Harbor Storage Engine                   │
│   - SQLite WAL Indexer & Graph Engine                  │
│   - Plain-Text Markdown Filesystem Access              │
│   - Zero Network Dependencies or Open Ports            │
└────────────────────────────────────────────────────────┘
ComponentOperational ResponsibilityConstraints
Harbormaster AdapterNetwork I/O, JSON-RPC, capability checksStrictly read-only; no disk writes
Storage EngineFile indexing, relational graph queriesNever binds to network sockets
IPC BoundaryIn-process Python / Rust interfaceThread-safe, bounded memory queues
Failure RecoveryRestarts without risking database locksACID transactions remain untouched

Clean Interface Contract

The adapter queries engine capabilities through explicit interface methods:

from typing import Protocol, List, Dict, Any
 
class EngineQueryInterface(Protocol):
    def get_note_metadata(self, note_id: str) -> Dict[str, Any]:
        ...
 
    def query_graph_neighbors(self, note_id: str, depth: int) -> List[str]:
        ...
 
    def get_system_telemetry(self) -> Dict[str, Any]:
        ...
 
class HarbormasterRpcHandler:
    def __init__(self, engine: EngineQueryInterface):
        self._engine = engine
 
    def handle_query_neighbors(self, params: dict) -> list:
        note_id = params.get("noteId")
        depth = min(int(params.get("depth", 1)), 3) # Strict depth clamp
        return self._engine.query_graph_neighbors(note_id, depth)

Boundary Isolation Verification

Verify that adapter processes cannot mutate filesystem records:

# Verify process user and group permissions
ps -o pid,user,group,comm -p $(pgrep -f "harbormaster")
 
# Test read-only constraint enforcement
curl -s -X POST http://127.0.0.1:8765/protocol/v1/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"kpp.notes.write","params":{"title":"Exploit"}}' | grep -i "error"
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1004 - Separating API Adapters from Storage Engines](HBM-1004 - Separating API Adapters from Storage Engines)

Graph View