# `SuperPi.RPC.Server`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/rpc/server.ex#L1)

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`).

# `ack_watch_batch`

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`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `enqueue_watch_event`

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`

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`

# `run_stdio`

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`

---

*Consult [api-reference.md](api-reference.md) for complete listing*