Cheetah / Cheetah documentation

Commands, acknowledgement, and delivery

A command crosses three distinct boundaries before product work can finish: the application admits an intent, the delivery system makes one runtime attempt, and the client governs local execution. The command envelope carries enough identity and timing information to keep those boundaries explicit.

Command envelope

{
  "type": "command",
  "command_id": "cmd-7f94",
  "issued_at_ms": 1784455300000,
  "command": {
    "name": "read_page",
    "target": { "tab_id": 42 },
    "params": { "selector": "main" }
  },
  "response": {
    "stream_key": "browser-main/jobs",
    "mode": "rpc"
  },
  "timeout_ms": 30000,
  "deliverable_by_ms": 1784455345000,
  "delivery_sequence": 18,
  "trace_id": "trace-81ae",
  "tags": ["profile-import"]
}

Capture instructions and central-authorization evidence can extend the envelope without changing command identity. Nested user-supplied data is subject to reserved-key validation; server-produced payload references have a separate validated shape.

Admission and the first attempt

Application admission decides whether the delivery subsystem should accept responsibility for the command. In a distributed deployment, accepted work can enter the logical client's Redis mailbox before a connection owner attempts the socket write. Mailbox notification is only a wake-up hint; reconnect checks and periodic sweeps recover admitted work when a hint is lost.

deliverable_by_ms limits when the first attempt may begin. If the command expires while still provably unattempted, the delivery system can terminate it without asking a late client to run the action. delivery_sequence preserves admission order for one logical client; it is not a global order across clients or tenants.

Immediately before the first WebSocket attempt, the dispatcher binds the command and any RPC correlation to the current instance_id. Work that is still provably unattempted may follow a stable logical client through a reconnect to a replacement runtime. Once sending starts, an ambiguous write is not automatically replayed. Closing the uncertain socket prevents a network ambiguity from becoming an automatic duplicate execution.

A successful transport write proves only that the socket owner handed the frame to its transport. It does not prove that the runtime received, validated, or accepted it.

Wire validation and runtime normalization

The shared TypeScript transport validates a command before dispatch. Serialized commands use the nested command and response objects shown above. Handler code receives a normalized runtime command with a flat command_type, normalized params, response information, and the same identities and timing fields.

WireProtocolMessage and the transport-specific WebSocket and REST unions describe serialized shapes. RuntimeProtocolMessage describes objects used after normalization; ProtocolMessage remains its compatibility name. Custom transports should narrow to the correct wire sub-union before switching because WebSocket families use type while ordinary HTTP return families use kind.

If an invalid wire command still contains enough identity for a correlated response, the reference client does not acknowledge it. It returns a terminal wire_validation_error through HTTP. If correlation cannot be recovered, it reports wire_validation_error_unidentified on the reserved _cheetah/errors stream. This distinguishes “the transport received bytes” from “a valid command entered dispatch.”

The exact meaning of acknowledgement

After a valid command enters the shared dispatch path, the client sends a payload-free acknowledgement over the WebSocket. It does so before handler lookup, local policy, approval, or execution. The server accepts the acknowledgement only from the authenticated principal, logical client, and exact runtime instance bound to that send attempt, and only when accepted is true.

ACK therefore means:

This bound runtime received a valid command and admitted it to its dispatch path.

It does not mean that the target still exists, the action is supported, central or local policy allowed it, a user approved it, a handler began, or a side effect completed. A denial or handler error is returned later as application evidence; it does not rewrite the earlier delivery fact.

Client-governed execution

After acknowledgement, the composed runtime may resolve payload references, validate normalized arguments, combine central evidence with local policy and approval, preflight parser definitions, acquire a lease around the target, execute the handler with progress and cancellation facilities, perform supported capture, and form a terminal result or error.

The exact stages depend on the runtime and installed packages. A browser extension can own tabs and page adapters; a console runtime can own machine or process actions. The shared pipeline standardizes lifecycle, authority, and returned evidence without pretending that every environment has the same capabilities.

If a caller stops waiting, that does not automatically cancel the client action. If an action is safe to cancel, the product contract must define cancellation and the runtime must support it. Otherwise, late terminal evidence can still arrive and should be reconciled by command ID.

Returned messages and state