Sync, conflict resolution, audit replay.

/ 01Oplog basics

Every device that opens a fieldbook has a device_id and a monotonic clock. Mutations append to oplog.json with both, plus the hash chain. The oplog is the source of truth for "what happened, in what order, on what device" — the SQLite database is the materialised state.

If two devices edit the same file independently, both extend their oplog. Reconciling them is the work of delta & merge.

/ 02Delta & merge

Three operations form the sync primitive:

// What's in source that's not in target?
pub fn delta(source: &Oplog, target: &Oplog) -> Vec<OplogEntry>

// Merge remote entries into local oplog (dedupes by ID)
pub fn merge(local: &mut Oplog, remote: &[OplogEntry]) -> Vec<OplogEntry>

// Apply merged entries to the SQLite database
pub fn apply_to_database(fb: &mut Fieldbook, entries: &[OplogEntry]) -> usize

Cell-level conflicts (same record, same field, two devices updated independently) are resolved last-write-wins by timestamp. If timestamps are exactly equal, deterministic tie-break by device_id lex order.

/ 03Hash chain verification

Both oplog and audit log are hash-chained. Every entry's hash covers the previous entry's hash + the entry's own canonical JSON payload. Tampering with any entry breaks the chain from that point onward.

Verification runs in three places:

• On file open — fast pre-flight; failure marks the file broken
• On merge — both chains verified before merging
• On demand — fieldbook validate FILE --strict

The WASM verifier is identical bit-for-bit to the Rust verifier — same RFC 8785 canonicalisation, same SHA-256. An auditor can re-verify any export in-browser without trusting the host.

/ 04Audit replay

The audit log is queryable by actor, resource, time range, and event class. Replay lets you reconstruct who saw what:

fieldbook audit FILE \
  --actor user@firm.com \
  --from 2026-01-01 --to 2026-03-31 \
  --action DocumentViewed,DocumentDownloaded \
  --format json

Replay output is itself audit-logged (under AuditQueryExecuted) so the chain of custody is preserved when the log is exported for regulator or court.

/ 05Network sync (mDNS)

For offline-first scenarios — two laptops at a meeting, a phone at a site visit — Fieldbook supports direct device-to-device sync over the LAN via mDNS. No cloud, no server.

1. Advertise

   Open a file; the client advertises the file ID + device ID on _fieldbook._tcp.

2. Discover

   Other devices on the same network see the advertisement and offer to sync if they have the same file ID.

3. Mutual TLS

   Sync uses mTLS with a one-time pairing code displayed on both devices.

4. Delta exchange

   Each device computes a delta against the other's clock and sends only the missing entries.

/ 06Conflict UI

For text fields where last-write-wins is too coarse, the UI surfaces a conflict resolver:

• Side-by-side diff of the two values
• "Keep mine" · "Keep theirs" · "Merge manually"
• Manual merge opens both versions in a three-way editor with the common ancestor

Decisions emit MergeConflictsResolved audit events with the chosen outcome and the discarded value's hash.