Stax Digital Garden

HBM-1008 - Read-Only Protocol Invariants

2 min read

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

Read-Only Protocol Invariants

Read-Only Protocol Invariants: Monochromatic ice blue phosphor P7 vector CRT macro depicting unidirectional diode gates and reflective barrier planes enforcing read-only protocol invariants

Extensibility in local knowledge architectures introduces clear operational risks. When third-party scripts, visualization tools, or automated query agents interface with personal databases, an errant or compromised module must never be permitted to corrupt files or mutate relational records.

Harbormaster addresses this risk by defining hard, non-negotiable read-only invariants within the Knowledge Provider Protocol (KPP) JSON-RPC loopback adapter. Rather than relying on discretionary client conventions, the adapter enforces immutability at the protocol gateway.

Protocol Method Isolation

The KPP JSON-RPC specification partitions methods into explicit namespaces. Any method call bearing a query.*, read.*, or inspect.* prefix maps exclusively to read-only handlers backed by read-only database connections.

If a client session initiates with read-only authority tokens, any invocation attempting to call mutation methods (mutate.*, write.*, delete.*) is rejected before argument deserialization occurs.

# protocol_guard.py - Enforcing method immutability
import json
 
READ_ONLY_PREFIXES = ("kpp.read.", "kpp.query.", "kpp.inspect.", "kpp.system.ping")
 
def evaluate_rpc_invocation(session_scope: str, request_payload: bytes) -> dict:
    call = json.loads(request_payload)
    method = call.get("method", "")
    
    if session_scope == "read_only":
        if not any(method.startswith(prefix) for prefix in READ_ONLY_PREFIXES):
            return {
                "jsonrpc": "2.0",
                "id": call.get("id"),
                "error": {
                    "code": -32601,
                    "message": f"Method '{method}' denied under read-only capability token"
                }
            }
            
    return {"status": "authorized", "method": method}

By decoupling method inspection from application storage logic, the protocol prevents accidental side effects.

OS-Level Storage Protection

Protocol enforcement is paired with operating system boundaries. Read-only adapters query local SQLite databases configured with immutable connection URIs (file:vault.db?mode=ro). Even if a vulnerability existed in the JSON-RPC parsing engine, the underlying operating system process cannot obtain write locks or alter blocks on disk.

# Verify SQLite database opens in strict read-only mode via CLI probe
sqlite3 "file:vault.db?mode=ro" "PRAGMA query_only;"
  • Directus Target: harbormaster
  • Garden Source Reference: MOC - Harbormaster Protocol, MOC - Bosun PKM Tools
  • Garden Source Reference: [HBM-1008 - Read-Only Protocol Invariants](HBM-1008 - Read-Only Protocol Invariants)

Graph View