runa/docs/protocol.md

# Runa Protocol

`runa-protocol` defines versioned request, response, and event data contracts
for clients and the `runa-server` dispatcher. It is independent of transport
and runtime implementation; the server currently dispatches requests
in-process, with no network endpoint or authentication.

## Version 1

Every request and response carries `version: 1`. Requests also carry a
non-empty `request_id` used to correlate the response. A server must reject
unsupported versions with `unsupported_version` rather than interpreting a
request using a different contract. Events carry the protocol version and do
not have a request ID.

Requests have a tagged command object:

```json
{
  "version": 1,
  "request_id": "req-1",
  "command": {
    "operation": "send",
    "parameters": {
      "actor_id": 7,
      "message": { "kind": 2, "value": 9 }
    }
  }
}
```

The version 1 operations are behavior publication, rollback, lookup, source
retrieval, actor spawn, send, tick, inspect, actor listing, event retrieval,
stop, restart, pause, resume, cancellation, and behavior installation.
Migration closures are intentionally excluded: they are host callbacks, not
portable wire values.

Responses echo the request ID and carry either a typed reply or a protocol
error. Events use a separate versioned envelope. Actor and behavior snapshots
are wire DTOs, not serialized runtime objects; implementation identities are
represented by their stable display strings. The server maps known service
failures to the defined error codes and otherwise uses `runtime_failure`
rather than claiming a more specific category.

`get_events` drains and returns the events currently accumulated by this
single-worker image. It is not a durable subscription or replayable event log.
Any future network transport must also impose message and request-size limits
before dispatch; the in-process protocol crate does not impose byte limits.

The current validation checks the protocol version, request ID, positive
actor/revision identifiers where required, non-empty behavior names, mailbox
capacity, and instruction budget. Behavior-name grammar, actor existence,
current behavior revisions, mailbox capacity at send time, and all runtime
invariants remain authoritative at the application-service boundary.