Module operator 

The operator command-channel client: JSON-lines over a Unix domain socket (ADR-051 D6;).

degenbot fleet posture [show|set] and degenbot path [add|discover] are clients of a LIVE bot’s OperatorServer. The versioned wire protocol is documented in src/degenbot/operator/operator_channel.py; that header + the server’s framing are read-only contract and this module must not drift from them.

Wire shape (one JSON object per line, newline-terminated)

Request lines nest the payload at the top level (the exact shape Python’s send_command writes and the server’s _decode_request reads):

{"op": "add_path", "payload": {"steps": [...], "directions": [true]}}
{"op": "discover", "payload": {"bound": 5}}
{"op": "set_fleet_posture", "payload": {"cordon_enter_events": 2}}
{"op": "get_fleet_posture", "payload": {}}

Response lines:

{"ok": true, "detail": "..."}
{"ok": true, "detail": "", "effective": {...}}
{"ok": false, "error": "..."}

Division of validation

This client adds wire hygiene only - an unknown cordon_* key, an empty posture patch, an unknown hop-family string - refused BEFORE the socket is touched by validate_posture_patch / parse_hop_token. The six cordon values are DOMAIN validation and stay the authority of the server (PosturePolicyPatch::validate in the workers core); this crate deliberately does not import or re-implement it, so a client built earlier never second- guesses a host built later.

Socket resolution

--socket > DEGENBOT_OPERATOR_SOCKET (the shell-environment layer, read through the degenbot-config EnvVars seam) > ~/.config/degenbot/operator.sock (the example driver’s plug-in default). No typed config-file key exists for the operator socket, so the env layer is the only config surface; a future typed key would slot in above the env layer at exactly one site.

Structs

PathStep

One hop in an add_path steps array.

PosturePatchEntry

One cordon_* entry in a partial posture patch.

Enums

PathDirection

A --direction choice: one bit applied to every hop.

PathFamily

A pool family on the wire (V2 / V3 / V4).

PosturePatchValue

A set_fleet_posture threshold value.

WireRequest

The four ops the live host serves, encoded as one request line.

WireResponse

A decoded response frame.

Constants

FLEET_POSTURE_THRESHOLD_KEYS

The six fleet-posture threshold key names set_fleet_posture accepts (the typed DEGENBOT_FLEET_CORDON_* keys). Anything else is refused at the wire before it reaches the host.

SIM_INTAKE_FLOOR_RESTORE

The documented sentinel for --cordon-sim-intake-floor: the literal null (case-insensitive) restores half the slot cap; any other value is a threshold. The host’s PosturePolicyPatch carries this as the Some(None) override.

SOCKET_DEFAULT

The plug-in default socket path (the settlement-bot example’s --operator-socket default family). The leading ~ expands against HOME.

SOCKET_ENV

The environment variable naming the live bot’s operator socket (the shell layer of the cascade). Empty is treated exactly like unset.

Functions

decode_response

Decode one response line. A malformed/non-object/missing-ok frame is a protocol error; a well-formed {"ok": false, ...} frame (including the host’s unknown-op reply) is WireResponse::Err, never a panic.

parse_hop_token

Parse one FAMILY:ADDRESS[:HASH] hop token into a wire PathStep (mirrors _parse_hop). Family is case-insensitive; the V4 hash is carried only for V4 and only when non-empty.

parse_sim_intake_floor

Parse the cordon_sim_intake_floor flag text: the literal null (case-insensitive) is the documented restore sentinel (SIM_INTAKE_FLOOR_RESTORE), anything else must be an unsigned integer.

render_json_sorted

Render an effective object as one compact JSON object with its top-level keys sorted - the Python CLI’s json.dumps(effective, sort_keys=True). None renders {} (the Python response.get("effective", {}) default).

resolve_socket

Resolve the operator socket: --socket > DEGENBOT_OPERATOR_SOCKET > ~/.config/degenbot/operator.sock. The winning value has a leading ~ expanded against HOME through the env seam.

send_request

Send one request to the operator host and decode its single response line.

validate_posture_patch

Client-side wire hygiene for a posture patch: no unknown cordon_* key and no empty patch. Mirrors the host’s handle_fleet_posture_op guard messages; the host’s typed PosturePolicyPatch::validate remains the value authority.