SuperPi.RPC.Server (super_pi v0.1.0)

Copy Markdown View Source

Day-1 JSON-RPC 2.0 Server over TCP, Unix Domain Socket, and stdio (REQ-RPC-01..REQ-RPC-05, REQ-PBT-07).

Exposes the complete SuperPi.Durable and SuperPi.Conversation.Machine harness to external clients (VS Code extensions, Neovim plugins, desktop apps, web frontends, and CLI wrappers).

Supported JSON-RPC 2.0 Methods

  • session.open — Creates or opens a durable conversation (%{conversation_id: id, seq: seq}).
  • session.submit — Submits user input with mode ("queue", "steer", "write").
  • session.fork — Forks a conversation at at_entry_id with asOf document rewind.
  • session.compact — Runs context compaction ("manual", "threshold", "overflow").
  • session.context — Derives the active LLM context via the 10 normative rules.
  • session.watch — Subscribes the client connection to session.event notifications with bounded K = 2 in-flight backpressure (REQ-RPC-03).
  • session.ack — Acknowledges receipt of a session.event batch (batch_id), advancing the client's K = 2 flow-control window and flushing coalesced pending deltas (REQ-RPC-04).
  • ui.respond — Delivers the user's answer to a server-initiated ui.request prompt (REQ-RPC-05).

Summary

Functions

ack_watch_batch(client_state, batch_id)

Processes a client session.ack for batch_id (REQ-RPC-04, REQ-PBT-07). Removes batch_id from in_flight; if coalesced_queue is non-empty and map_size(in_flight) < 2, flushes all coalesced events in a single consolidated session.event batch.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

enqueue_watch_event(client_state, event_payload)

Enqueues a server-to-client session.event notification under the K = 2 ack-clocked backpressure contract (REQ-RPC-03, REQ-RPC-04, REQ-PBT-07)

handle_rpc_payload(raw_json, client_state)

Processes a single raw JSON-RPC 2.0 line and returns {reply_map | nil, updated_client_state, outbound_notifications}. Pure state-transition function that is also used directly by ExUnitProperties (REQ-PBT-07).

new_client_state()
port(server_pid)
run_stdio(opts \\ [])

Serves one client on standard input and output until stdin closes. One JSON-RPC message per line in each direction.

start_link(opts \\ [])

Functions

ack_watch_batch(client_state, batch_id)

Processes a client session.ack for batch_id (REQ-RPC-04, REQ-PBT-07). Removes batch_id from in_flight; if coalesced_queue is non-empty and map_size(in_flight) < 2, flushes all coalesced events in a single consolidated session.event batch.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

enqueue_watch_event(client_state, event_payload)

Enqueues a server-to-client session.event notification under the K = 2 ack-clocked backpressure contract (REQ-RPC-03, REQ-RPC-04, REQ-PBT-07):

  • If map_size(client_state.in_flight) < 2, immediately emits a session.event JSON-RPC notification with a fresh batch_id and records batch_id in in_flight.
  • If map_size(client_state.in_flight) >= 2, coalesces event_payload into client_state.coalesced_queue without emitting any wire frame until the client calls session.ack.

handle_rpc_payload(raw_json, client_state)

Processes a single raw JSON-RPC 2.0 line and returns {reply_map | nil, updated_client_state, outbound_notifications}. Pure state-transition function that is also used directly by ExUnitProperties (REQ-PBT-07).

new_client_state()

port(server_pid)

run_stdio(opts \\ [])

Serves one client on standard input and output until stdin closes. One JSON-RPC message per line in each direction.

stdout carries only protocol lines, so route logs to stderr first (bin/super-pi rpc --stdio does this with SUPER_PI_LOG_STDERR=1).

start_link(opts \\ [])