Application API

AppNode is the Python service that product code calls. It is not an HTTP server and it does not own a client socket. It turns application-shaped work into an admitted Cheetah command, coordinates a terminal waiter when requested, exposes payload-free delivery evidence, and reads presence and retained messages.

Bind the application identity first

Most request handlers and jobs already know which authenticated user they serve. Bind that identity once and use the returned view:

scoped = app_node.for_user(user_id)

command_id = await scoped.send_command(
    client_id="primary-browser",
    command={
        "name": "navigate",
        "params": {"url": "https://example.com/"},
    },
    options=SendOptions(),
)

UserScopedAppNode constructs Routing(user_id, client_id) internally. Its stream methods accept suffixes instead of full canonical keys, and it does not expose an unrestricted history store. This reduces the number of call sites that can accidentally mix user identity and routing.

Infrastructure code that already owns a trusted Routing can call raw AppNode methods. In shared-tenancy mode, raw identity strings are not accepted at the public boundary. Enter through the restricted shared-tenancy surface with an authenticated tenant principal; a client-supplied or reconstructed principal string is not proof.

Choose the operation by the question

Question	Operation
Can this work be admitted for a logical client?	`send_command()`
Can I admit it and wait for one terminal result or error?	`send_command_and_wait()`
What happened to the delivery attempt?	`get_delivery_status()`
Can I locally wait on an existing RPC registration?	`await_result()`
Which progress or terminal messages are stored now or arrive soon?	`wait_for_responses()`
What complete messages are retained for a command or stream?	`history_for()` or `get_history()`
Which clients are currently present?	`get_presence()`
How do I store a value and grant a client a bounded reference to it?	`store_payload()`, `store_and_sign()`, or raw `sign_ref()`

These are deliberately different observations. A returned command ID proves dispatcher acceptance. A delivery ACK proves that the bound runtime accepted a valid command frame. An RPC resolution proves that one qualifying terminal message was correlated. History supplies the complete retained message. None alone proves an external side effect that only the application or target system can observe.

Read this section in order

Command admission and dispatch covers the exact command shape, SendOptions, authorization and reconnect admission, durable handoff, and pre-dispatch failures.

Terminal results and delivery status separates RPC observation from delivery evidence and explains timeouts, attempt binding, terminal errors, and unsafe retry conditions.

Response waiting and history covers progress waiters, complete returned messages, destructive consumption, pagination, deletion, and backend qualifications.

Presence and payload references covers current-client discovery and the bounded history-backed payload-reference helpers.

For the same behavior as a system journey, read Command and evidence. For construction of the service and its dependencies, use Server composition.