[Oliver-Johnson]

Checks

• I have not edited index.html or sw.js without understanding the PWA cache implications
• The version string in index.html has been bumped (format: Version YYYY-MM-DD.N). Left for promotion, see notes
• manifest.json is still valid JSON (unchanged)
• The app works offline after the change (no change to sw.js; sync just waits when offline)
• CI passes (version consistency, .nojekyll, symlinks, conflict markers, plus a new sync server test job)

What this changes

Before: Sync only pushed a full snapshot from one device to the server. On launch the app pulled back only missing fibre, sugar and sodium, plus today's targets. A desktop never saw what a phone logged.

After: every device pointed at the same server shares one log. That covers entries, notes, weight, water, exercise, fasts, recipes, custom foods, targets and settings. A sync runs a few seconds after a change, on opening the app, on coming back to it or back online, and every 2 minutes while open. Settings shows when the last sync ran.

How it merges: each device keeps a fingerprint of every record from its last sync and merges record by record.

• A record that is unchanged on one side takes the other side's edit or deletion.
• If both sides changed a record, this device's edit wins, and an edit beats a delete.
• Water added on two devices on the same day is summed.
• A device's first sync is a union. Against an old one-way copy this device wins; on a server others already sync to, the server's targets and settings win over a new device's defaults.

Safety:

• It never syncs while the tour's demo data is active.
• A sync that would delete more than a fifth of either side (and more than 10 records) pauses, and Sync now asks first.
• Clear All Data forgets the last sync, so the next sync restores from the server instead of deleting everywhere.
• Unreadable data stops the sync instead of counting as empty.
• It waits while a sheet is open or someone is typing, and tabs take turns with navigator.locks.

Server: new GET/PUT /sync/state. The revision is a hash of the stored file, so direct edits (agents filling in fibre) are picked up. A PUT carries the revision it started from and gets 409 if another device synced in between. Writes are atomic and locked, and unknown top-level keys are kept. The old POST /sync/food-log keeps working until the file has two-way data, then refuses, so an outdated app can't overwrite it. An app talking to a server without /sync/state falls back to the old push and fibre fill-in.

Docs: the developer guide, sync server README and README describe two-way sync, and the changelog has a beta entry.

Testing done

• 12 server unit tests in sync-server/test_server.py, run by a new sync-server job in CI.
• 24 two-device checks against a real server. These cover concurrent edits, deletes on each side, water from both devices, the destructive-sync pause, Clear All Data restoring, a 409 retry, an edit made mid-sync, and the tour never syncing.
• 7 upgrade checks: an old one-way copy on the server, and a server not yet updated.
• 40/40 smoke tests on this branch locally (Chromium).
• Ran CI's checks locally. All pass.

Notes for reviewer

This is a draft. It goes to beta testers first via #9. Before it leaves draft it needs a version bump and a What's New entry on top of master.

Known trade-off: on the first sync after upgrading from one-way sync, an entry deleted since the last one-way upload comes back once, which is the safe side. The same amount of water added on two devices between syncs counts once.

This builds on #2, #1 and #3 (merged in), so its own changes are commits ba5aaeb and 53d73ed.

🤖 Generated with Claude Code

https://claude.ai/code/session_019C67htt6KV7fmxsGCf5FR7

---

Generated by Claude Code