Nerve Protocol
Nerve Protocol v1 connects the Workbench UI to workbench_server over authenticated HTTP and WebSocket. Contracts define transport-neutral operations/events; the protocol package implements sessions and recovery; the server provides authorization, persistence, handlers, and stream composition.
Roles and catalogs
Section titled “Roles and catalogs”The schema reserves workbench_server, ui, desktop_shell, and cli roles so every strict envelope can name its source and target. The implemented product link today is the Workbench UI (ui) to workbench_server; the desktop shell manages daemon lifecycle outside that session, and there is no active CLI Protocol v1 client.
The operation catalog declares method schemas, roles, capabilities, idempotency, and transport exposure. The public event catalog declares payload, source roles, delivery class, and routing.
Session and streams
Section titled “Session and streams”After hello → welcome → ready, the client sends the complete desired stream/cursor set. Each stream independently becomes live, replays retained events, requests a snapshot, or is unavailable. Replay arrives before buffered live events.
A client advances a cursor only after its reducer successfully processes an event. If bounded buffers cannot preserve sequenced ordering, the session closes with resync_required and reconnect recovery rebuilds state.
HTTP and WebSocket share typed handlers where operations expose both transports. Large files/logs, OAuth callbacks, binary transfer, and selected configuration remain HTTP or out-of-band.
Follow one client flow
Section titled “Follow one client flow”- Start with the message envelope and session lifecycle to negotiate
hello → welcome → ready. - Use the HTTP mapping for a typed request, or send the same catalog operation through WebSocket RPC when exposed there.
- Install the complete desired stream set using subscriptions and recovery; process event batches before advancing each cursor.
- On a gap or retention miss, apply the repository snapshot and resubscribe instead of inventing a second recovery path. The examples show the messages together.
Versioned reference
Section titled “Versioned reference”Read the Protocol v1 reference for envelopes, lifecycle, streams, HTTP mapping, errors/security, extension rules, examples, status, and coverage.