The dangerous implementation is not one that never works. It is one that works in a demo and loses its boundaries under real networks and real data volume. Use monotonic clocks for in-process duration because they do not move backward; transmit an authoritative absolute deadline plus skew allowance across machines.
Distributed correctness comes from idempotency keys, leases, monotonic versions, and reconcilable facts—not an assumption of one delivery. A timeout means unknown outcome, not confirmed failure.
Engineering boundaries and tradeoffs
This capability crosses clients, networks, and servers, so a local optimization can create a system failure. Decisions must constrain both endpoints, persisted truth, and operating budgets together.
- Model Instant, Duration, and WallTimestamp separately, ban Date.now deltas for retry budgets, and reschedule from the remaining deadline after resume.
- Define success, degraded, cancelled, and failed terminal states before UI, storage, and metrics consume the same state.
- Use explicit capability negotiation so older clients receive an explained fallback instead of a half-working state.
The delivery standard for Why Timeouts Need Monotonic Clocks Instead of Wall Time is a usable normal path, convergent failures, bounded resources, and a state users can understand. The result is a production capability that can be explained, degraded safely, and rolled back—not a demo that works once.
How it fails in production
Failure and success must share one state model. An error toast that neither releases resources nor propagates a terminal state leaves dirty work for the next recovery attempt.
- A backward NTP correction extends wall-clock locks, while a forward jump expires every lease at once.
- A boolean failure cannot distinguish retryable, user-action, and permanent refusal, producing an endless loop.
- User or task IDs in metric labels create high-cardinality cost and leak unnecessary identity into diagnostics.
Turn testing into a closed loop
Do not stop verification when the final action succeeds. Count side effects, measure wait time, inspect privacy, and prove the next run begins from a clean baseline.
- Inject forward and backward jumps, two-hour sleep, and timezone changes; duration logic must follow monotonic progress and distributed deadlines converge conservatively.
- Race refresh, cancel, timeout, and remote completion in one scheduling window; assert one terminal state and one side effect.
- Before release, record success rate, p50/p95/p99 latency, error classes, and resource high-water marks with explicit rollback thresholds.
A capability becomes maintainable when it degrades safely, repetition adds no side effects, and its signals reveal a fault before user reports do.