Stabilize cloud sync with snapshot conflict overwrite, persistent offline queue, and optimistic concurrency

[Copilot]

This PR hardens cloud synchronization so stale-state conflicts converge without reload loops, offline edits survive reload/crash, and concurrent writes are guarded with optional optimistic concurrency checks.

Changes Made

Client sync hardening (packages/markdown/assets/cloud.js)

• Keeps snapshot-overwrite conflict resolution as the deterministic stale-state recovery path (no reload-based recovery loop).
• Persists offlineQueue in localStorage and reloads it on startup.
• Automatically flushes persisted offline queue when back online.
• Tracks and stores stateChecksum from server responses for concurrency matching.
• Sends concurrency preconditions on normal writes and uses forced overwrite only in explicit conflict-recovery paths.
• Clears persisted sync metadata (offlineQueue, checksum, last event id) on auth reset/logout.

Cloud API optimistic concurrency (platforms/cloud/routes/store.js)

• Adds optional request guards:
  • ifMatchLastEventId
  • ifMatchChecksum
  • forceOverwrite (explicit override path)
• Returns stateChecksum in:
  • GET /api/store/:hyperbookId
  • POST /api/store/:hyperbookId/events
  • POST /api/store/:hyperbookId/snapshot
• Returns 409 conflict when preconditions fail, including server sync head/checksum context.

Regression tests

• Added packages/markdown/tests/cloudSync.test.js:
  • verifies conflict resolution path avoids reload loops,
  • verifies offline queue persistence and reconnect flush behavior.
• Added platforms/cloud/tests/storeOptimisticConcurrency.test.js:
  • verifies checksum responses,
  • verifies stale revision/checksum conflicts,
  • verifies forced overwrite behavior.

Validation

• Targeted markdown cloud sync tests pass.
• Cloud platform tests pass, including new optimistic concurrency coverage.
• Root test run passes after required package builds in dependency order.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperbook-4fwa	Ready	Preview, Comment	May 15, 2026 7:13am

[mikebarkmin]

@copilot Is there some to improve about the cloud sync?

[Copilot]

@copilot Is there some to improve about the cloud sync?

Yes — a few meaningful improvements are still possible:

1. Persist offlineQueue in IndexedDB/localStorage so queued writes survive tab close/crash.
2. Add optional server-side optimistic concurrency (revision/checksum) to reduce last-writer-wins overwrites.
3. Add targeted tests for conflict + offline-reconnect flows to assert “no reload loop” behavior.

If you want, I can implement (1) first as the next incremental hardening step.

[mikebarkmin]

@copilot do all three

[Copilot]

@copilot do all three

Implemented all three in commits 03b6beb and cf48be2:

• persisted offline queue across reload/crash and auto-flush on reconnect,
• optional optimistic concurrency (ifMatchLastEventId / ifMatchChecksum, with forceOverwrite escape hatch),
• targeted regression tests for conflict + offline-reconnect paths to verify no reload loop.