Durable. Offline-first. Deterministic.

Vix Sync is the core synchronization engine of Vix.cpp.

It guarantees that every operation:

• is persisted before being sent
• is never lost
• is retried deterministically
• converges to a consistent state

Real-world systems are not reliable:

• network drops
• servers restart
• requests fail halfway

Traditional systems:

• lose data
• duplicate requests
• become inconsistent

Vix Sync solves this with a simple rule:

Write locally. Persist first. Sync later.

1. Durability first

   • Every operation is stored before any network call

2. Deterministic retries

   • Retry logic is reproducible and replayable

3. Offline-first

   • The system works without network

4. Safe convergence

   • Eventually, all nodes reach a consistent state

Vix Sync is composed of small deterministic building blocks:

Local Write
↓
WAL (Write-Ahead Log)
↓
Outbox (durable queue)
↓
SyncWorker
↓
Transport (HTTP / P2P / custom)
↓
Done / Retry / Failed

A durable unit of work.

struct Operation {
  std::string id;
  std::string kind;
  std::string target;
  std::string payload;
};

Append-only log:

• crash-safe
• replayable
• ordered

Wal wal({ .file_path = "./.vix/wal.log" });

wal.append(record);
wal.replay(0, handler);

Durable operation queue:

• enqueue
• claim
• complete
• retry

auto id = outbox->enqueue(op, now);
outbox->claim(id, now);
outbox->complete(id, now);

Deterministic exponential backoff:

RetryPolicy retry;
retry.base_delay_ms = 500;
retry.factor = 2.0;
retry.max_attempts = 8;

Processes operations:

• fetch ready ops
• send via transport
• mark done / fail

Orchestrates workers:

SyncEngine engine(cfg, outbox, probe, transport);
engine.tick(now);

Run examples with:

vix run examples/<file>.cpp

vix run examples/01_outbox_basic.cpp

vix run examples/02_outbox_retry_and_failure.cpp

vix run examples/03_wal_append_and_replay.cpp

vix run examples/04_sync_worker_success.cpp

vix run examples/05_sync_worker_permanent_failure.cpp

vix run examples/06_sync_engine_requeue_inflight.cpp

vix run examples/07_local_write_wal_outbox_engine.cpp

vix run examples/08_local_write_offline_then_recover.cpp

If the process crashes at any point, the system can recover fully.

Because:

• WAL stores intent
• Outbox stores state
• Retry is deterministic

Use it when you need:

• offline-first systems
• reliable message delivery
• distributed state convergence
• retry-safe APIs
• edge or unstable network environments

• not a message broker
• not a queue system like Kafka
• not a distributed database

It is:

a durable sync layer for real-world unreliable systems

• P2P transport
• conflict resolution
• multi-device sync
• edge replication

MIT License © Gaspard Kirira