Sync / Replicated state

Replicated state: foldkit-sync + foldkit-durable

Some state has to keep working when the network is gone, survive a reload, and end up the same on every device and tab that edits it. This guide takes one such feature from its first edit to a running server, with both packages:

  • foldkit-sync runs on the client. It keeps the edits a user makes in a local outbox, shows them at once, and reconciles them with the server's answer.
  • foldkit-durable runs on the server. It decides the one order every replica ends up in, keeps the snapshot and log on SQLite, and answers a retried operation without applying it twice.

Neither replaces your application. Model, Message, and update remain the state machine; a durable edit is one of your existing Messages, recorded. The packages are also separable: Sync works against any server that speaks its exchange, and Durable journals any operation stream.

If you only want to know what the system is, four sentences cover it:

1. A durable operation is an existing Foldkit Message plus replication metadata.
2. What the user sees = committed snapshot + pending local edits, replayed.
3. Sync owns the replica; Durable owns the authoritative order.
4. Reconciliation moves the committed base, drops settled edits, replays the rest.

Everything below is those four sentences, built.