network-resiliencelisted

# Network resilience ## The constraint The connection is not slow. It is intermittent, asymmetric, and dishonest — it disappears mid-request, reports itself as live while carrying no traffic to your origin, and costs the user money per megabyte from a prepaid bundle they top up in fifty-cent increments. Latency to your origin is 300–800ms before congestion. The device changes network three times on a matatu ride to work. Design for a connection that fails *ambiguously*. Total failure is easy: you show an error. The expensive case is the request that neither succeeds nor fails, and the user who taps again. ## Hard rules | ID | Rule | Severity | |---|---|---| | NET-001 | Render from local state first; never block first paint on a network call. | critical | | NET-002 | Queue every state-changing request durably before attempting it. | critical | | NET-003 | Every state-changing request carries a client-generated idempotency key. | critical | | NET-004 | Pending, queued, and failed states are visible and honest in the UI. | critical | | NET-005 | Set explicit request timeouts sized for the target network, not the default. | warning | | NET-006 | Retry with capped exponential backoff and jitter; never tight-loop. | warning | | NET-007 | Treat the connectivity flag as a hint, not a fact. | warning | | NET-008 | Honour metered-connection and data-saver signals. | warning | | NET-009 | Declare a conflict-resolution policy for every entity that syncs. | warning | | NET-010 | Batc