refactor(sync): replace legacy examples with structured sync scenarios and update README

Author: GaspardKirira

README.md

@@ -1,2 +1,243 @@
-# sync
-Offline-first sync engine (WAL, outbox, retries).
+# Vix Sync
+
+**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
+
+---
+
+## Why Vix Sync exists
+
+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.
+
+---
+
+## Core principles
+
+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
+
+---
+
+## Architecture
+
+Vix Sync is composed of small deterministic building blocks:
+
+```text
+Local Write
+↓
+WAL (Write-Ahead Log)
+↓
+Outbox (durable queue)
+↓
+SyncWorker
+↓
+Transport (HTTP / P2P / custom)
+↓
+Done / Retry / Failed
+```
+
+---
+
+## Components
+
+### 1. Operation
+
+A durable unit of work.
+
+```cpp
+struct Operation {
+  std::string id;
+  std::string kind;
+  std::string target;
+  std::string payload;
+};
+```
+
+### 2. WAL (Write-Ahead Log)
+
+Append-only log:
+
+- crash-safe
+- replayable
+- ordered
+
+```cpp
+Wal wal({ .file_path = "./.vix/wal.log" });
+
+wal.append(record);
+wal.replay(0, handler);
+```
+
+### 3. Outbox
+
+Durable operation queue:
+
+- enqueue
+- claim
+- complete
+- retry
+
+```cpp
+auto id = outbox->enqueue(op, now);
+outbox->claim(id, now);
+outbox->complete(id, now);
+```
+
+### 4. RetryPolicy
+
+Deterministic exponential backoff:
+
+```cpp
+RetryPolicy retry;
+retry.base_delay_ms = 500;
+retry.factor = 2.0;
+retry.max_attempts = 8;
+```
+
+### 5. SyncWorker
+
+Processes operations:
+
+- fetch ready ops
+- send via transport
+- mark done / fail
+
+### 6. SyncEngine
+
+Orchestrates workers:
+
+```cpp
+SyncEngine engine(cfg, outbox, probe, transport);
+engine.tick(now);
+```
+
+---
+
+## Examples
+
+Run examples with:
+
+```bash
+vix run examples/<file>.cpp
+```
+
+### Basic
+```bash
+vix run examples/01_outbox_basic.cpp
+```
+
+### Retry & failure
+```bash
+vix run examples/02_outbox_retry_and_failure.cpp
+```
+
+### WAL
+```bash
+vix run examples/03_wal_append_and_replay.cpp
+```
+
+### Worker
+```bash
+vix run examples/04_sync_worker_success.cpp
+```
+
+### Permanent failure
+```bash
+vix run examples/05_sync_worker_permanent_failure.cpp
+```
+
+### Engine requeue
+```bash
+vix run examples/06_sync_engine_requeue_inflight.cpp
+```
+
+### End-to-end (local-first)
+```bash
+vix run examples/07_local_write_wal_outbox_engine.cpp
+```
+
+### Offline to recovery
+```bash
+vix run examples/08_local_write_offline_then_recover.cpp
+```
+
+---
+
+## Key invariant
+
+If the process crashes at any point, the system can recover fully.
+
+Because:
+
+- WAL stores intent
+- Outbox stores state
+- Retry is deterministic
+
+---
+
+## When to use Vix Sync
+
+Use it when you need:
+
+- offline-first systems
+- reliable message delivery
+- distributed state convergence
+- retry-safe APIs
+- edge or unstable network environments
+
+---
+
+## What Vix Sync is NOT
+
+- 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
+
+---
+
+## Future
+
+- P2P transport
+- conflict resolution
+- multi-device sync
+- edge replication
+
+---
+
+## License
+
+MIT License
+© Gaspard Kirira
+

examples/01_outbox_basic.cpp

@@ -0,0 +1,88 @@
+/**
+ *
+ *  @file 01_outbox_basic.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.
+ *  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ *
+ */
+// Run:
+//   vix run examples/sync/01_outbox_basic.cpp
+
+#include <chrono>
+#include <filesystem>
+#include <iostream>
+#include <memory>
+
+#include <vix/sync/Operation.hpp>
+#include <vix/sync/outbox/Outbox.hpp>
+#include <vix/sync/outbox/FileOutboxStore.hpp>
+
+static std::int64_t now_ms()
+{
+  using namespace std::chrono;
+  return duration_cast<milliseconds>(
+             steady_clock::now().time_since_epoch())
+      .count();
+}
+
+static void reset_dir(const std::filesystem::path &dir)
+{
+  std::error_code ec;
+  std::filesystem::remove_all(dir, ec);
+  std::filesystem::create_directories(dir, ec);
+}
+
+int main()
+{
+  using namespace vix::sync;
+  using namespace vix::sync::outbox;
+
+  const std::filesystem::path dir = "./build/examples/sync/basic";
+  reset_dir(dir);
+
+  auto store = std::make_shared<FileOutboxStore>(FileOutboxStore::Config{
+      .file_path = dir / "outbox.json",
+      .pretty_json = true});
+
+  auto outbox = std::make_shared<Outbox>(
+      Outbox::Config{
+          .owner = "example-basic"},
+      store);
+
+  Operation op;
+  op.kind = "http.post";
+  op.target = "/api/messages";
+  op.payload = R"({"text":"hello"})";
+
+  const auto t0 = now_ms();
+  const std::string id = outbox->enqueue(op, t0);
+
+  std::cout << "enqueued: " << id << "\n";
+
+  auto ready = outbox->peek_ready(t0, 10);
+  std::cout << "ready count: " << ready.size() << "\n";
+
+  const bool claimed = outbox->claim(id, t0 + 1);
+  std::cout << "claimed: " << (claimed ? "yes" : "no") << "\n";
+
+  const bool done = outbox->complete(id, t0 + 2);
+  std::cout << "completed: " << (done ? "yes" : "no") << "\n";
+
+  auto saved = store->get(id);
+  if (saved)
+  {
+    std::cout << "final status: "
+              << (saved->status == OperationStatus::Done ? "Done" : "Other")
+              << "\n";
+  }
+
+  return 0;
+}