Offline-first message buffer with sequence-number-ordered replay for ManagedClient

[rambudithe]

Problem Statement

When an MQTT client reconnects after a connectivity
outage, the .NET MQTTnet library provides no built-in
mechanism to:

1. Buffer messages locally during the outage without
   blocking the application
2. Persist buffered messages to disk so they survive
   process restarts
3. Replay messages in guaranteed chronological order
   when connectivity is restored

The MQTTnet wiki explicitly acknowledges this gap:

"It is recommended to use the regular client and
doing the reconnect stuff etc. via your own code."

However, most developers implementing their own reconnect
logic make a critical mistake: they replay in FIFO queue
order or timestamp order. During connectivity outages,
device clocks drift from NTP synchronization — meaning
timestamps become unreliable for ordering. Messages
replayed in timestamp order arrive at downstream
consumers out of sequence after clock correction.

Real-World Impact

In enterprise IoT deployments across geographically
distributed locations — financial services, healthcare,
industrial safety — this silent data loss has direct
compliance and operational consequences.

We observed message loss rates of 0.3%–4.7% across
branch locations before solving this problem.

The Key Insight — Sequence Numbers Not Timestamps

The correct solution assigns a monotonically increasing
sequence number at write time — immune to clock drift —
and uses that for ordering rather than device timestamps.

Reference Implementation

I have built an open source .NET library addressing
this gap:

GitHub: https://github.com/rambudithe/EdgeSyncBuffer
NuGet: https://www.nuget.org/packages/EdgeSync.Buffer