Document the sync engine's actual consistency guarantees - #457
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
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.sourcererfile 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 typecheckclean,npm test527 passed across 30 files, and I checked tag balance in both edited HTML files.