Skip to Content
Front pageLabsLabs, projects & CCNA notes

Sync engine

Comma's serverless sync over Google Drive, the interoperability defects found between the phone and web apps, and the simplification audit that was never implemented.


Comma synchronises a phone and a browser without a server. Each device reads and writes encrypted files in the driver's own Google Drive appDataFolder.

Model

ElementImplementation
TransportGoogle Drive appDataFolder, one private folder per app
Merge rulePer-row last-write-wins on syncUpdatedAt
DeletesSoft deletes with syncDeletedAt tombstones
Change formatOne delta change log per push: comma-cl-{device}-{ts}.cmlog
CompactionA snapshot (.cmsnap) after 30 logs, then deletion of the logs it covers
CursorA set of applied log names, not a single watermark
EncryptionAES-256-GCM with a password-derived key

The protocol is implemented twice: src/services/sync/ in TypeScript for the phone and web/src/services/sync/ in JavaScript for the web. The two implementations must stay byte-compatible.

Interoperability audit, 2026-07-03

An audit on 2026-07-03 checked whether the two apps could sync through the shared Drive folder. It found that they could not. The two codebases had grown different column names and value types for the same records.

FindingCause
OAuth project mismatchThe web app and the phone app used different Google OAuth clients, so each saw a different appDataFolder.
Shift platform keyThe web wrote platformId. The phone required a NOT NULL column named platform.
GoalsThe two apps stored goals in different models.
VehiclesThe web used nickname and active. The phone used name and isActive.
MerchantsBoth apps minted their own ids. merchants.name was UNIQUE, so a same-name merchant from the other device aborted the whole apply transaction.
Poison logsA bad row in an immutable log failed on every sync and blocked every log behind it.
TimestampsThe phone wrote ISO strings. The web expected epoch milliseconds.
Full-row writesThe web's put() replaced the row and erased web-only fields.
Shift platform rowsThe phone hard-deleted rows, so removals never reached the other device.
Platform activationWeb platform rows carried no syncUpdatedAt and were never pushed.

Two further defects appeared during the fixes:

  • Historical data never synced. Rows created before the sync columns existed had syncUpdatedAt = 0. Push collected only rows above the cursor, which was also 0.
  • Seed rows could overwrite real data. A new browser stamped its default platform rows with Date.now(). Under last-write-wins, those defaults would replace the phone's settings.

All findings were fixed the same day. The fix made the phone's schema canonical and made every web row carry both key sets, through a translation layer in interopShape.js.

Simplification audit, 2026-07-12

A second audit reviewed the engine after the fixes. Its verdict: the core model was correct, and the engine was oversized for the data.

MeasureValue
Phone implementationAbout 1,830 lines
Web implementationAbout 1,300 lines
Largest real vault tested185 shifts
Expected data sizeSingle-digit megabytes

The audit proposed these changes:

FindingProposal
Two byte-compatible implementationsOne platform-agnostic core with injected adapters
Delta logs, compaction and an applied-set cursorOne full-state file per device
Poison-log quarantineRemoved by the full-state design, which re-evaluates each row on every sync
Dual-key interop layerOne canonical wire format
Independently minted merchant idsDeterministic ids derived from content
Overwrite audit log for financial rowsDropped or downgraded

The audit status was "proposal, nothing implemented yet". The proposal was not implemented before Comma was retired.

Outcome in MileWage

MileWage does not sync between peers. The server holds the only copy of the records, and the phone sends raw fixes to it. There is one schema, one merge point and no change log.

The trade-off is recorded in Decision: retire Comma.

Back to top