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 Field	Description	Target Threshold
`active_adapters`	Count of authenticated connected modules	< 16 concurrent clients
`p99_latency_ms`	Round-trip latency for JSON-RPC evaluation	< 5.0ms on local loopback
`buffer_overflows`	Count of dropped events from slow clients	0 under normal operation
`memory_rss_bytes`	Resident 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