Offline writes now queue + apply optimistically instead of throwing.
On reconnect, the queue drains automatically; conflicts and rejections
surface as one-time SnackBars so the user knows their edit didn't land.
- Drift schema v3: `pending_writes` table (verb + payload + baseline +
tries + last_error). Negative ids serve as cache placeholders for
offline-created rows until replay assigns the server id.
- Each write repository (notes, tasks, projects, milestones, events)
now catches NetworkException, applies the change to cache (with a
fresh `nextTempId()` for creates), and enqueues the API call.
- Edits to a still-queued offline-created row coalesce into the
original create payload — only one server call per row, in order.
- Deletes of still-queued offline-created rows drop the queue entry
and the cache row; no server call ever happens.
- New WriteQueue service drains the queue oldest-first.
Server-wins on `updated_at` baseline check (notes/tasks/projects);
last-writer-wins for milestones/events (no getOne available).
4xx → drop + surface as `rejected`; conflict → drop + `overwritten`;
404 on update → drop + `missing`; 5xx/network → keep + retry next
online cycle.
- Replay fires on AuthStatus → authenticated transitions
(cold-start, came-back-online, login).
- OfflineBanner shows "Retry (N)" with the pending-writes count.
- Distinct ServerException added so 4xx no longer masquerade as
NetworkException — the queue can drop them instead of looping.
flutter analyze clean; 21 tests pass (3 new for QueueFailure messaging).
Phase 4 (read-only UI indicators on cached/temp rows) still ahead.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Phase 1 cached only notes. Phase 2 brings the read-through pattern to every
domain the app reads in bulk:
- Drift schema v2: 5 new cached_* tables + onUpgrade migration. Calendar
events use range-scoped read/write (replaceEventsInRange) so disjoint
month fetches don't clobber each other; milestones are per-project.
- Wrap TasksRepository, ProjectsRepository, MilestonesRepository, and
ChatRepository (conversation list only) with NetworkException fallback.
Writes hit the API then sync the cache.
- New EventsRepository wrapping EventsApi; calendar_provider and
event_form_sheet repointed at the repository.
- OfflineBanner now surfaces getLatestSync() — most-recent timestamp
across all domains — so the hint reads sensibly regardless of screen.
flutter analyze clean; existing tests pass. Phase 3 (offline write queue)
and Phase 4 (read-only UI indicators) still to come.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
First slice of the tier 2 offline mode work tracked in Fable #147.
Notes are the only domain wired so far; this PR establishes the
shape and proves the round-trip end-to-end before extending to tasks
/ projects / events / etc. in phase 2.
Local store
- Adds drift ^2.20.0 + sqlite3_flutter_libs ^0.5.24 + path ^1.9.0
runtime deps and drift_dev / build_runner dev deps.
- New lib/data/local/database.dart: FabledDatabase with CachedNotes
(mirroring the Note model 1:1; tags stored as JSON-encoded text) and
SyncMetadata (per-domain last_synced_at). Database file lives at
$appDocs/fabled_cache.sqlite; opened lazily in a background isolate.
- fabledDatabaseProvider on the existing api_client_provider; closes
the DB when the ProviderScope disposes.
Repository pattern
- NotesRepository now takes (NotesApi, FabledDatabase). Reads attempt
the network first; on success the response is written to the cache.
On NetworkException reads fall back to the cache (rethrowing if it
is empty so fresh-install offline still surfaces the network error).
- Writes (create/update/delete) hit the server then sync the cache;
offline write queueing is phase 3 and explicitly not wired here.
- AuthStatus.offline stays owned by AuthNotifier.verify()'s heartbeat;
this repo deliberately doesn't poke that state.
OfflineBanner
- Reads notesRepository.lastSyncedAt(); when present, swaps
"Offline — showing cached data." for "Offline — last sync X min
ago." A 30s timer refreshes the relative-time string while the
banner is mounted.
- Falls back to the generic message if no cache exists yet (fresh
install offline).
Verification
- flutter analyze: No issues found
Out of scope (later phases per the task body)
- Tasks / projects / milestones / events / conversation list / journal
day caching (phase 2 — same wrapper pattern, repeated)
- Generic write queue with conflict resolution on updated_at (phase 3)
- Read-only UI indicators on screens that depend on cached data
(phase 4)
- Full offline chat (out of scope; needs a local model)
- RAG / search over cached content (out of scope)
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
bvandeusen