Reliability and recovery
Cheetah improves reliability by making identity, lifecycle, evidence, and uncertainty explicit. It cannot prevent a browser from stopping a service worker, a user from closing a page, a process from crashing, or a network from failing between an external effect and its reported result.
The practical goal is therefore not to make failures disappear. It is to preserve enough meaning that the system can distinguish reconnection from replacement, reject stale data, reconstruct current state from the right authorities, and leave domain-level uncertainty to the product that understands it.
A stable client can have several runtime instances over time, and one runtime can use several connections. Recovery rebuilds current knowledge from platform, server, history, and product-owned sources; it does not replay every uncertain action.
A disconnected socket does not define the client
The stable client_id identifies a logical installation within an authenticated scope. A runtime creates an instance_id for its current execution lifetime. That instance can use a new WebSocket connection after a brief interruption without becoming a replacement.
When the same instance reconnects, it repeats connection setup and re-establishes its route. The server does not automatically fail all pending RPC waits merely because the socket closed; the same runtime may still return an outcome through HTTP or reconnect.
The client reacts to remote transport loss by cancelling active remotely originated commands. This cancellation is cooperative. A well-behaved handler checks its abort signal or lease validity and stops at a safe boundary, but code cannot undo an external effect that already happened.
A new instance is a stronger boundary
When a fresh browser service worker or another replacement runtime starts for the same stable client, it uses a new instance_id. Registering that replacement updates the current route and can fail pending correlation fenced to the old instance. In a coordinated deployment, the system can also request closure of a superseded connection on another node.
Exact-instance cleanup prevents an old connection's delayed disconnect handler from removing the newer route. Returned messages can also be rejected when their instance does not match the current lifetime expected for the work.
This fencing protects association inside Cheetah. It does not prove that the old runtime had no external effect before it disappeared. If instance A submitted a form and vanished before reporting it, instance B cannot infer from replacement alone whether the submission occurred.
Browser reconstruction begins with current platform state
A restarted browser runtime cannot recover arbitrary JavaScript memory. It can inspect and report supported current platform state: for example, open tabs and windows, tracked worker resources, and other information its platform adapters expose.
A full state report enters through authenticated ingestion and is adapted into normalized contexts. The context registry replaces the client's reported set, so resources absent from the new complete snapshot can disappear from the reconstructed view. Server-owned fields, such as selected task-assignment or ownership data, remain governed by server rules rather than being overwritten by an incomplete client description.
This is snapshot reconstruction, not event sourcing. It provides a trustworthy view of what the platform reported at an observation point. It does not reconstruct every event that happened while the runtime or server was unavailable.
Different recovery sources answer different questions
| Source | What it can tell the system | What it cannot prove |
|---|---|---|
| Current client connection | Which runtime can be reached now. | Whether earlier work completed. |
| Full platform state report | Which supported contexts exist at observation time. | The complete event history or arbitrary lost memory. |
| Server registry and scheduling state | Current route, ownership, and assignments managed by server components. | The physical world's current state. |
| Retained response history | Which applicable messages passed ingestion and were retained. | Every outbound command or exactly-once execution. |
| Product business record | Intended and committed domain transitions. | Client-local facts it never observed. |
Recovery combines these authorities instead of asking one store to impersonate all of them. For example, a terminal waiter may time out while a late accepted result remains in history. An application can inspect that retained evidence before deciding whether to retry.
Timeouts protect observations and resources
Cheetah has several clocks: connection heartbeat, RPC wait, response collection, parser execution, payload retrieval, client lease, worker assignment, content-script bridge, and product-specific operation timeouts. They protect different resources and produce different evidence.
Before admission, an application send can wait a bounded time for a recently seen logical client to reconnect. That wait creates no command or RPC state. After admission, delivery has a separate deadline, and an RPC execution deadline begins when sending starts. An explicit await_result(..., timeout_ms=...) can stop only one local observation while the registered RPC, remote work, other waiters, and late history remain active.
An RPC timeout means that one waiter did not receive a qualifying terminal signal before its deadline. It does not cancel every layer, delete retained history, or prove that the handler never ran. A worker-assignment timeout can release scheduling ownership without proving that the remote action stopped. Increasing a generic "timeout" without identifying the stage can therefore hide the real problem.
Replay depends on domain semantics
Cheetah does not promise exactly-once external effects. Response deduplication can suppress repeated ingestion of the same message identity or sequence position. Instance fencing can stop stale results from satisfying current correlation. Neither mechanism travels backward in time to prevent a handler from acting twice.
Safe recovery depends on the action:
- a read can often be repeated and compared;
- an idempotent write can carry a stable domain operation key;
- an action can query the external system before retrying;
- a compensating operation may repair a known partial result;
- a high-impact unknown outcome may require human review.
These are product decisions because only the product knows the business meaning of the effect. Cheetah contributes the client, instance, command, trace, and retained-message identities needed to make the decision with evidence.
What "comparatively reliable" means
Within its boundaries, Cheetah provides structured connection and instance handling, explicit authority, coordinated routing, validation and ingestion fencing, retained evidence, lifecycle hooks, state reconstruction, and observable failure stages. Those facilities are a stronger substrate than an application-specific WebSocket message with implicit retry rules.
The remaining limits are equally important. Platform processes remain volatile, local authority remains local, cancellation remains cooperative, distributed notifications can be missed, retention depends on composition and policy, and external side effects are not part of one rollback-capable transaction.
A reliable Cheetah application is designed around both halves of that statement: it uses the framework's explicit guarantees and gives every uncertain domain effect an appropriate idempotency or reconciliation rule.