Protocol overview
Cheetah protocol 1.0 joins two independently protected transports into one command exchange. The server delivers commands over the current client's WebSocket. The client returns progress, results, errors, events, telemetry, and state through an authenticated HTTP service. Stable identities and correlation IDs—not an assumption that both directions share one connection—join the two paths.
The numbered checkpoints are evidence boundaries. Each proves only what the component at that boundary could observe; acknowledgement, execution, and external completion are different facts.
Why the protocol is asymmetric
A long-lived WebSocket is well suited to reaching a browser extension, console process, or other connected runtime that may move between networks. Returned data has a different scaling and security profile. Sending it through an HTTP edge lets the host authenticate each return, apply request limits, and scale ingestion independently from connection ownership.
The consequence is intentional: an authenticated WebSocket does not grant authority to a later HTTP request. The HTTP host establishes the trusted principal again. The client includes correlation and runtime identities in the body, but body fields alone never authenticate a user or tenant.
Message families
| Direction | Transport | Family | Purpose |
|---|---|---|---|
| client to server | WebSocket | hello | request a protocol session and advertise runtime information |
| server to client | WebSocket | hello_ack | accept or reject the session and, when accepted, provide effective configuration |
| client to server | WebSocket | heartbeat | refresh liveness for the already authenticated route |
| server to client | WebSocket | command | deliver one admitted action to a specific logical client and runtime attempt |
| client to server | WebSocket | ack | confirm that a valid command entered the client's dispatch path |
| client to server | HTTP | ordinary client message | return progress, result, error, event, or telemetry |
| client to server | HTTP | state_report | publish a complete platform-specific runtime snapshot |
The deprecated ownership_change family is recognized only so that it can be rejected deterministically. Context ownership does not move through that message. A config_update shape exists in TypeScript declarations but has no active protocol 1.0 runtime path.
Identities that join the exchange
client_id is the stable logical installation within a trusted principal. instance_id identifies one running client lifetime. A transport reconnect can preserve both; a replacement runtime keeps the logical client ID and creates a new instance ID. command_id identifies the server-issued work, while message_id identifies one HTTP delivery from the client.
These identities have different jobs. A command attempt is fenced to the runtime instance that made it. A result is correlated to its command, retained under a trusted principal and stream, and deduplicated as an HTTP delivery. Reusing one identity where another is required weakens replacement safety or makes recovery ambiguous.
Evidence, not implied completion
The dispatcher accepting responsibility, a socket write succeeding, the client sending an acknowledgement, a handler returning, and an external side effect completing are separate events. Protocol 1.0 preserves those distinctions. In particular:
- a successful socket write does not prove client receipt;
- an acknowledgement does not prove local permission, handler entry, or completion;
- a caller timeout does not prove that client work stopped;
- retaining a terminal message proves that ingestion accepted it, not that every product database transaction also completed;
- retry deduplication does not turn client execution into exactly-once execution.
Applications should name the fact they observed instead of collapsing these checkpoints into a generic “success.” This is especially important during reconnects, timeouts, and incident recovery.
Reading this section
Connection and negotiation defines the hello exchange, transport posture, readiness, heartbeat, and runtime replacement.
Commands, acknowledgement, and delivery defines the command envelope, delivery admission, runtime normalization, and the exact meaning of ACK.
Returned messages and state defines HTTP result envelopes, sequence and deduplication rules, state reports, retention, and host responsibilities.
Validation, errors, and conformance collects identifier, payload, reserved-key, malformed-message, and implementation conformance requirements.