Stax Digital Garden

HBM-1007 - Adapter Registry and Health Diagnostics

2 min read

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

Adapter Registry and Health Diagnostics

Adapter Registry and Health Diagnostics: Monochromatic ice blue phosphor P7 vector CRT macro showing five stacked adapter status channels with heartbeat telemetry and health crosshairs

Operating multiple pluggable modules requires visibility into active connections, memory consumption, and protocol latency. When an adapter becomes unresponsive or leaks memory, operators need clear diagnostic endpoints to isolate faults without restarting the entire knowledge engine.

Harbormaster maintains an internal adapter registry and exposes machine-readable health metrics over its loopback interface. Operators and supervision daemons can inspect registered clients, check queue depths, and measure round-trip latency in real time.

Diagnostic Metrics Architecture

The telemetry collector samples internal queues and adapter latencies every ten seconds:

┌──────────────────────┐      ┌──────────────────────┐
│  Desktop Status Bar  │      │  Graph Visualizer    │
└──────────┬───────────┘      └──────────┬───────────┘
           │                             │
           ▼                             ▼
┌────────────────────────────────────────────────────┐
│          Harbormaster Adapter Registry             │
│   - Tracks active sessions & token expirations     │
│   - Aggregates request counters & error rates      │
└──────────────────────────┬─────────────────────────┘
                           │
                           ▼
           GET /protocol/v1/health (JSON Telemetry)
Metric FieldDescriptionTarget Threshold
active_adaptersCount of authenticated connected modules< 16 concurrent clients
p99_latency_msRound-trip latency for JSON-RPC evaluation< 5.0ms on local loopback
buffer_overflowsCount of dropped events from slow clients0 under normal operation
memory_rss_bytesResident set size of the Harbormaster daemon< 35 MB baseline

Health Response Schema

{
  "status": "healthy",
  "uptime_seconds": 86400,
  "adapters": [
    {
      "client_id": "desktop-status-bar",
      "connected_since": "2026-09-16T10:00:00Z",
      "scopes": ["kpp.graph:read"],
      "queue_depth": 0
    }
  ],
  "metrics": {
    "requests_total": 14200,
    "errors_total": 0,
    "p99_latency_ms": 1.2
  }

CLI Diagnostic Probing

Query daemon telemetry from the terminal:

# Query machine-readable health diagnostic endpoint
curl -s http://127.0.0.1:8765/protocol/v1/health | jq '.'
 
# Measure loopback response time
curl -o /dev/null -s -w "Total Time: %{time_total}s\n" http://127.0.0.1:8765/protocol/v1/health
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1007 - Adapter Registry and Health Diagnostics](HBM-1007 - Adapter Registry and Health Diagnostics)

Graph View