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

Component	Operational Responsibility	Constraints
Harbormaster Adapter	Network I/O, JSON-RPC, capability checks	Strictly read-only; no disk writes
Storage Engine	File indexing, relational graph queries	Never binds to network sockets
IPC Boundary	In-process Python / Rust interface	Thread-safe, bounded memory queues
Failure Recovery	Restarts without risking database locks	ACID 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"