diff --git a/docs/MOBILE_DELEGATION_ROADMAP.md b/docs/MOBILE_DELEGATION_ROADMAP.md index de11fb2..dbe65b3 100644 --- a/docs/MOBILE_DELEGATION_ROADMAP.md +++ b/docs/MOBILE_DELEGATION_ROADMAP.md @@ -250,11 +250,14 @@ Execute in **flexible order**; prefer **small commits**. ## Block I — Optional sync engine (`@bytelyst/sync`) -**Last.** Mobile currently hydrates via **REST + Zustand**. Replacing with **`@bytelyst/sync`** requires mapping entities (notes, workspaces, inbox) to backend contracts and conflict rules — verify with backend before swapping. +**Decision for this handoff:** defer **`@bytelyst/sync`** adoption and keep the current `@bytelyst/offline-queue` mutation retry model. See [`MOBILE_SYNC_DECISION.md`](./MOBILE_SYNC_DECISION.md). + +**Later.** Mobile currently hydrates via **REST + Zustand**. Replacing with **`@bytelyst/sync`** requires mapping entities (notes, workspaces, inbox) to backend contracts and conflict rules — verify with backend before swapping. ### I.1 Done criteria (only if attempted) - [ ] Parity with current hydration + offline behavior +- [x] Handoff decision recorded: defer `@bytelyst/sync` until backend sync contracts and conflict rules are explicit - [ ] Update [`AGENT_TASK_ROADMAP.md`](./AGENT_TASK_ROADMAP.md) - [ ] Commit: `feat(mobile): adopt @bytelyst/sync` (large; may split) diff --git a/docs/MOBILE_SYNC_DECISION.md b/docs/MOBILE_SYNC_DECISION.md new file mode 100644 index 0000000..2a0cd91 --- /dev/null +++ b/docs/MOBILE_SYNC_DECISION.md @@ -0,0 +1,42 @@ +# 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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 929cc48..9d8e3b2 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -510,6 +510,7 @@ Detailed implementation plans live under `docs/roadmaps/`. - **Active runtime smoke gap** — platform-service, extraction-service, mcp-server, blob, telemetry, diagnostics, flags, kill switch, and NoteLett backend health need documented and automated smoke checks. Tracked by production-readiness P2.2-P2.4 and P8.4. - ~~**Blocker** — Product identity not finalized~~ **Resolved:** locked as NoteLett (`e1fde25`) - **Deferred** — `@bytelyst/react-native-platform-sdk` adoption is intentionally deferred for release handoff; mobile uses direct shared `@bytelyst/*` clients instead. See `docs/MOBILE_PLATFORM_SDK_DECISION.md`. +- **Deferred** — `@bytelyst/sync` adoption is intentionally deferred for release handoff; mobile keeps the narrower `@bytelyst/offline-queue` retry model until backend sync/conflict contracts are explicit. See `docs/MOBILE_SYNC_DECISION.md`. - ~~**Deferred** — Blob-backed artifacts and upload/download flows~~ **Resolved:** SAS-based blob client (`196b210`) - ~~**Deferred** — Fully integrated approval/review/audit UX~~ **Resolved:** batch review, review notes, agent timeline across web + mobile (`ca3cdba`, `f8a4c18`) - ~~**Deferred** — Persisted saved views~~ **Resolved:** backend CRUD + web client + UI (`bdbf387`, `12d9009`) diff --git a/docs/roadmaps/04_MOBILE_ROADMAP.md b/docs/roadmaps/04_MOBILE_ROADMAP.md index bc5b9f2..33c469d 100644 --- a/docs/roadmaps/04_MOBILE_ROADMAP.md +++ b/docs/roadmaps/04_MOBILE_ROADMAP.md @@ -29,7 +29,7 @@ Stack: React Native + Expo + TypeScript - [x] Lightweight local editing - [ ] Notification handling -- [ ] Offline queue / sync polish +- [ ] Offline queue / sync polish (`@bytelyst/sync` deferred; see `../MOBILE_SYNC_DECISION.md`) - [x] Approvals inbox scaffold if in MVP scope - [x] Basic artifact metadata viewing scaffold if in MVP scope