Skip to main content

Migration Plan

:::info Source Sourced from services/sync-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules​

  • VectorClock semantics (F06) frozen M0 end; never change merge behavior.
  • Sync protocol (F07) frozen M0 end; additive within /sync/v1/; breaking → /sync/v2/.
  • Delta window (30 days) is a platform invariant; changing it requires all clients to update.

2. Protocol Evolution (within v1)​

Additive Changes (safe)​

  • New entity types registered.
  • New fields in push/pull request/response (clients ignore unknown).
  • New conflict policies (e.g., crdt_rga for rich text).
  • New status codes (e.g., 207 for partial success on push).

Breaking Changes (require v2)​

  • Cursor format change that breaks existing clients.
  • VectorClock merge semantics change.
  • Push/pull response envelope restructure.
  • Scope naming convention change.

v2 Migration Procedure​

  1. Ship /sync/v2/ alongside /sync/v1/.
  2. New client SDKs use v2; old continue on v1.
  3. Dual-run for ≥ 1 milestone.
  4. Deprecate v1 with Sunset header.
  5. After all active devices upgrade: retire v1.

3. Database Evolution​

  • Additive columns on all tables.
  • Conflict policy enum additive.
  • Delta table partitioning: monthly; scheme changes require controlled migration.
  • Cursor format: v field in cursor allows format changes without breaking clients.

4. Registration Evolution​

  • New entity types: additive.
  • Removing entity type: deprecate; existing deltas age out (30d); clients stop requesting.
  • Changing conflict policy: requires migration plan per entity (e.g., lww → crdt_yjs for authoring drafts).

5. VectorClock Evolution​

  • Semantics frozen.
  • Adding metadata fields to VectorClock: additive (clients ignore unknown).
  • Never change merge algorithm.

6. Delta Retention Change​

  • Increasing from 30 days: safe (more data retained).
  • Decreasing: requires client SDK update + notification (forces more frequent sync).

7. Client SDK Evolution​

  • Client SDKs versioned; pinned to protocol version.
  • Forced upgrade: if v1 deprecated, client must upgrade within sunset window.
  • Backward-compatible: new SDK understands old cursor format.

8. Event Consumption Evolution​

  • New domain events consumed: additive.
  • Schema changes on consumed events: consumer inbox + schema registry handles.
  • Consumer tolerates unknown fields.

9. Yjs Integration Evolution (M5+)​

  • Yjs doc format: versioned; migration via snapshot + replay.
  • New shared types: additive.
  • Removing shared type: freeze + migrate existing docs.

10. Data Residency​

  • Sync data (cursors, mutations, deltas) pinned to tenant homeRegion.
  • Migration: move cursors + deltas; clients pull full state from new region.

11. GDPR​

  • Erase: delete cursors, mutations, conflicts for user.
  • Deltas referencing user: delete or anonymize depending on entity type's GDPR policy.

12. Changelog​

Per-release: new entity registrations, protocol extensions, conflict policy additions, cursor format version, delta retention changes, Yjs schema versions.