Stax Digital Garden

YMN-1005 - Local Stdio JSON-RPC Bridging

2 min read

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

Local Stdio JSON-RPC Bridging

Local Stdio JSON-RPC Bridging: Dual-trace Phosphor P31 emerald green and P4 paper white vector CRT macro showing dynamic cadence decay vectors, time delta ratios, and threshold horizon boundaries

Summary

Inter-process communication between knowledge tools should not expose vulnerable network ports or background HTTP servers. Yeoman exposes contact queries and ledger mutations via standard input/output JSON-RPC 2.0 protocol brokered by Harbormaster.

The Security Hazards of Local HTTP Daemons

Many desktop productivity tools run persistent background HTTP servers on 127.0.0.1. This design exposes the user’s private data to cross-site websocket hijacking, local port collision attacks, and excessive background resource consumption.

Yeoman strictly adheres to the Bosun Fleet Invariant: Zero Network / Zero Daemons. External processes communicate with Yeoman solely through standard input and standard output streams using the JSON-RPC 2.0 protocol, managed by the Harbormaster KPP coordinator.

+-------------------------------------------------------------+
|                Harbormaster KPP Stdio Pipeline              |
|                                                             |
|   +-----------------------+       +-----------------------+ |
|   | Caller (Trice/Editor) | ----> | Stdin JSON-RPC Stream | |
|   +-----------------------+       +-----------------------+ |
|                                               |             |
|                                               v             |
|   +-----------------------+       +-----------------------+ |
|   | Yeoman KPP Server     | <---- | yeoman.get_contact    | |
|   | (Python/Rust Subproc) | ----> | Stdout Response       | |
|   +-----------------------+       +-----------------------+ |
+-------------------------------------------------------------+

The Yeoman RPC Method Matrix

Yeoman implements four core JSON-RPC methods defined in the canonical fleet RPC schema:

MethodParametersReturn ValueDescription
yeoman.get_contact{"id": UUID}Contact Dossier JSONFetches a full contact record by URN
yeoman.list_cadence_due{"as_of": ISO_DATE}Array of Overdue ContactsReturns contacts exceeding cadence interval
yeoman.record_interactionInteraction Payload{"status": "recorded", "id": UUID}Appends an event to the ledger
yeoman.update_channels{"id": UUID, "channels": [...]}Updated Contact RecordMutates communication addresses safely

Request and Response Wire Format

A typical interaction recording request sent over stdio follows standard JSON-RPC 2.0 framing:

{
  "jsonrpc": "2.0",
  "id": "req-1001",
  "method": "yeoman.record_interaction",
  "params": {
    "contact_id": "0191fa30-1001-7000-8000-000000000001",
    "timestamp": "2026-09-17T15:00:00Z",
    "channel": "matrix",
    "summary": "Finalized PRM dispatch publication parameters."
  }
}

The Yeoman process processes the request, commits the note to disk, and replies over stdout:

{
  "jsonrpc": "2.0",
  "id": "req-1001",
  "result": {
    "status": "ok",
    "interaction_id": "0191fa30-1004-7000-8000-000000000099",
    "cadence_reset": true,
    "next_due_date": "2026-10-01"
  }
}

Process Isolation and Crash Safety

Because Yeoman runs as a child subprocess spawned on demand by Harbormaster:

  1. No ports remain open when the editor closes.
  2. An unexpected crash or memory panic cannot corrupt sibling tools.
  3. Multiple concurrent queries are queued deterministically through standard POSIX pipes.
  • Directus Target: yeoman
  • Garden Source Reference: MOC - Bosun PKM Tools, MOC - Fleet Operations
  • Garden Source Reference: [YMN-1005 - Local Stdio JSON-RPC Bridging](YMN-1005 - Local Stdio JSON-RPC Bridging)

Graph View