Skip to content

Document the sync engine's actual consistency guarantees - #457

Merged
tomcardoso merged 1 commit into
mainfrom
docs/issue-446-sync-guarantees
Jul 20, 2026
Merged

Document the sync engine's actual consistency guarantees#457
tomcardoso merged 1 commit into
mainfrom
docs/issue-446-sync-guarantees

Conversation

@tomcardoso

Copy link
Copy Markdown
Owner

Closes #446

Shared projects sync through a cloud-replicated SQLite file. That's the right tradeoff for a no-server, end-to-end-encrypted tool, but it cannot deliver what people generally assume from the word "sync" — and none of the real guarantees were written down anywhere a user would find them.

The contract being documented:

Eventually consistent, provided collaborators don't write within the same cloud-sync upload window. Concurrent writes fork the shared file at the provider level, and conflict resolution is last-write-wins by wall-clock timestamp at second granularity, so clients with skewed clocks can resolve conflicts backwards.

Changes

src/main/sync/engine.ts — design comment at the top stating the model and the three assumptions it rests on (whole-file replication that forks rather than merges; cross-machine wall-clock LWW; no way to distinguish "no changes" from "provider paused"), so future changes are made against a documented contract. It also records what is deliberately not shared, and why.

docs/guide.html — plain-language version in the collaboration section. Leads with the actionable rule (work a few minutes apart), then explains why, then covers what a Dropbox-style "conflicted copy" next to the .sourcerer file actually means — including don't delete it, it contains someone's work, which seemed the most important practical thing a user could get wrong.

docs/security.html — new "Shared projects" section before Backups, with a sidebar entry. Separates the encryption properties (unchanged and strong — the provider stores ciphertext) from the consistency properties (weaker, and worth stating plainly), so the honest caveat doesn't read as a weakening of the encryption story.

README.md — condensed version under How it works.

One thing beyond the issue's scope

The guide's "Not synced" note was left incomplete by #448, so I extended it to say that alert read state is personal to your own installation and marking an alert read doesn't clear it for collaborators. That decision was just made and undocumented; it belongs in the same note as the notes-scratchpad exclusion.

Testing

Docs and comments only — no behaviour change. npm run typecheck clean, npm test 527 passed across 30 files, and I checked tag balance in both edited HTML files.

Shared projects sync through a cloud-replicated file, which forks rather
than merges on concurrent writes and resolves conflicts last-write-wins
by wall-clock timestamp. None of this was stated anywhere user-facing.

- engine.ts: design comment stating the model and its assumptions, so
  future changes are made against a documented contract
- guide.html: plain-language version, including what a provider
  "conflicted copy" means and what to do about it
- security.html: new Shared projects section alongside the encryption
  notes, covering the LWW and clock-skew caveats
- README: condensed version in How it works

Also records the per-user alert read state settled in #448.

Closes #446

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tomcardoso
tomcardoso merged commit fdeaccc into main Jul 20, 2026
1 check passed
@tomcardoso
tomcardoso deleted the docs/issue-446-sync-guarantees branch July 20, 2026 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the sync engine's actual consistency guarantees (cloud-file substrate, LWW, clock skew)

1 participant