Commands and returned evidence
A Cheetah command is a distributed journey rather than one request-response call. Product intent is prepared by the application-facing server role, routed to the process that owns a live client connection, governed and executed inside the client, and reunited with the application through authenticated returned-data ingestion.
The stages are separate because each stage proves something different. A precise lifecycle lets the application respond to failure based on evidence instead of treating every timeout as "the action did not happen."
Blue shows the command path. Purple shows client-local execution. Green shows returned data and application observation. The numbered checkpoints are evidence boundaries, not a chain of exactly-once guarantees.
Keep one example in mind: product code asks a browser client to run collect_invoice_summary in a selected tab and return structured fields from the signed-in page.
1. Product intent becomes a command
Product code starts at the App role with an authenticated principal, a target client, an action name, parameters, a response mode, and any supported platform context or capture request. It does not construct a WebSocket frame or select the server process that owns the connection.
The App role creates server-owned command and trace identity. Configured central authorization runs before presence is exposed: it can deny the invocation or contribute a normalized decision that will later be combined with local policy. Only then does admission require a fresh connection or, for a recently seen logical client, wait a bounded time for reconnection. Unknown or stale clients fail without creating a command, RPC registration, or durable reservation. Optional preparation may resolve parser definitions or replace supported oversized fields with scoped payload references when those facilities are composed.
For an RPC-style call, terminal correlation is registered after packaging succeeds but before dispatch. It begins fenced to the principal, stable client, and command, without choosing a runtime instance yet. Registering first avoids the race in which a very fast terminal result arrives before the waiter exists; the dispatcher binds the actual instance only when a send attempt starts. The current runtime modes are rpc and none; none omits the terminal waiter but does not mean that the reference client sends no terminal message.
At the end of this stage, Cheetah can say that the application-facing boundary accepted and prepared the request. It cannot yet say that a socket send was attempted.
2. Dispatch admits work for the logical client
The command destination is the effective principal plus stable client_id, not whichever runtime happened to be present during application preparation. Dispatcher acceptance means the selected implementation accepted responsibility under its delivery policy. It does not prove client receipt or execution.
In one process, the direct dispatcher can move immediately toward the current socket. In a Redis-backed deployment, accepted work enters a durable logical-client mailbox within its configured delivery and retention policy. A notification wakes the likely WebSocket owner, but the notification is only a hint: reconnect checks and periodic sweeps recover queued work when a hint is lost. The connection registry identifies the current socket owner when an attempt is ready to begin.
Immediately before the first socket delivery attempt, the command and pending correlation are bound to the runtime instance that will receive that attempt. The dispatcher adds a delivery deadline and per-client delivery sequence to the wire command. Work that expires before an attempt is recorded as such; work that is still provably unattempted can follow a stable logical client to a replacement instance. Once an attempt becomes uncertain, Cheetah does not automatically replay it merely because a new route appears.
3. The WebSocket role attempts delivery
The WebSocket role owns the live connection and writes the command frame to it. A successful transport write is useful send evidence, but it cannot prove that the client runtime read or accepted the frame. If the write fails in a way that cannot establish whether the frame escaped, the delivery outcome is uncertain and the connection is treated accordingly.
For a valid remote command, the reference client sends an ACK before handler execution. The server accepts that ACK only from the authenticated logical client and runtime instance bound to the attempt, then records payload-free delivery evidence.
The ACK has a deliberately narrow meaning: the runtime received a valid command into its dispatch path. It does not mean that local policy allowed the action, approval was granted, the handler began, or an external side effect completed.
4. The client governs and executes the action
The shared client dispatcher surrounds the product or platform handler with a consistent pipeline. Depending on the runtime's composition, it can:
- locate the registered action;
- resolve supported payload references and encrypted envelopes;
- validate the normalized arguments;
- combine the central decision with local policy and any required approval;
- preflight requested parser information;
- acquire a lease around the target;
- execute the handler with cancellation, progress, and telemetry facilities;
- perform supported post-action capture;
- form a terminal result or error and release the lease.
Optional stages do not silently become mandatory. A browser runtime may wire payload retrieval and capture facilities that a simpler core composition does not. A handler still owns the actual page, file, process, or device effect.
Central and local authority narrow one another. A central allow cannot erase a local deny; one approval applies to the invocation being evaluated rather than rewriting future policy. Cancellation is cooperative. The runtime can abort its signal and suppress later publishing, but it cannot undo an HTTP request, click, file change, or other side effect that already crossed into an external system.
5. Progress and terminal outcomes return through HTTP
Commands travel outward over the current live WebSocket. Progress, results, errors, events, and state return through authenticated HTTP. The two directions can therefore be owned by different processes and scaled according to different workloads.
The host authenticates the HTTP request and derives the trusted effective principal. Client fields do not establish that user or tenant scope. The host routes ordinary response messages and full state reports to their appropriate REST-role methods.
For an ordinary response, the REST role validates the message, checks the current instance where applicable, suppresses immediate duplicates, and stores applicable history. It then notifies collectors. An accepted terminal result or error can resolve the pending RPC correlation.
History, notification, and correlation are intentionally distinct:
- history retains accepted application messages for later reading;
- notification tells a reader that relevant retained data may have changed;
- correlation gives one caller a timely terminal signal associated with its command.
A distributed notification or waiter can be missed or expire while retained history still contains an accepted result. Recovery therefore checks the appropriate durable evidence rather than treating one observation mechanism as the complete truth.
6. The application observes an outcome
An RPC wait completes when an accepted terminal result or error resolves its registered correlator. Progress does not complete the terminal wait. Application helpers can use the correlation metadata and history to obtain the retained message, while other workflows may inspect the same history later.
The application can now continue the invoice workflow. It still interprets the returned data and owns the business consequences. A successful Cheetah terminal outcome is evidence about the handler's reported result; it is not a universal proof that every external system now agrees with the product's business record.
Reading the checkpoints accurately
| Observation | What it establishes | What it does not establish |
|---|---|---|
| Application preparation complete | The App role accepted and prepared the command. | A delivery attempt. |
| Dispatcher accepted | The selected handoff accepted responsibility. | Client receipt or execution. |
| Socket write accepted | The socket owner handed the frame to transport. | Runtime receipt. |
| Client ACK accepted | The bound runtime accepted a valid frame into dispatch. | Permission, handler entry, or completion. |
| Progress accepted | A non-terminal update passed ingestion. | Eventual success or failure. |
| Terminal response accepted | A result or error passed current ingestion checks and can complete correlation. | Exactly-once external effects. |
| RPC timeout | The waiter received no qualifying terminal signal in time. | That the handler did not run. |
These boundaries are the basis for safe retry and recovery decisions. The next page explains how client identity, reconnection, reconstruction, and product-level reconciliation use them.