# Mobile Sync Decision

Status: active decision
Date: May 5, 2026
Decision: defer `@bytelyst/sync` adoption for the production-readiness handoff.

## Context

NoteLett mobile currently uses:

- REST hydration through `mobile/src/api/*`
- Zustand stores for notes, workspaces, prompts, inbox, and auth
- `@bytelyst/offline-queue` in `mobile/src/lib/offline-queue.ts` for failed note create/update retries
- auth-gated queue flushing from `mobile/src/app/_layout.tsx`

The shared `@bytelyst/sync` package provides an offline-first sync engine with entity mapping, persistent queue storage, pull/push cycles, conflict handling, retries, reconnect flushing, telemetry hooks, and configurable storage.

## Decision

Defer replacing the current mobile offline queue with `@bytelyst/sync` until NoteLett has explicit backend contracts for entity-level sync and conflict resolution.

The current queue is intentionally narrow: it retries note create/update mutations after transient failures while keeping reads as live REST hydration. That is suitable for the current handoff. Moving to `@bytelyst/sync` would require product decisions about stale reads, workspace membership changes, note version conflicts, agent-action review state, prompt/intake jobs, and blob-backed artifacts.

## Required Adoption Criteria

Adopt `@bytelyst/sync` later when these are defined and tested:

- entity map for notes, workspaces, relationships, tasks, artifacts, prompts, intake jobs, and agent actions
- backend endpoints that support pull windows, updated-since cursors, tombstones, and conflict responses
- conflict strategy for note title/body edits versus server-side versions and agent proposals
- product-scoped storage keys using `PRODUCT_ID`
- MMKV storage adapter parity and migration from the current offline queue key
- telemetry events for sync success, failure, conflict, queue depth, and retry exhaustion
- UX for sync status, stale data, retry failures, and conflict review
- tests proving parity with current note create/update offline behavior before removing `@bytelyst/offline-queue`

## Current Guardrails

- Keep `@bytelyst/offline-queue` as the mobile mutation retry foundation for this handoff.
- Do not add a second queue that can replay the same note mutation twice.
- Expand the current queue only where production-readiness P6/P7 require clear retry UX.
- Revisit `@bytelyst/sync` after backend sync contracts and mobile offline acceptance tests are explicit.