# V9-004 mobile offline persistence

Date: 2026-07-27

## Repository result

The Metis Expo client now has a versioned, bounded offline progress queue backed
by React Native AsyncStorage and live connectivity state from NetInfo. Offline
safe actions are persisted before the UI reports success. Online-only actions
are blocked without inventing progress, corrupt snapshots fail closed, rapid
actions are serialized, and unsuccessful delivery or acknowledgement
checkpointing retains the original event identity for an idempotent retry.

The learner surface exposes this state in one compact connectivity rail: current
network/sync phase, static bundle revision, and pending event count. It does not
claim server synchronization because an authenticated progress transport is not
yet configured.

Focused Jest coverage proves:

1. offline recording and restoration from the same storage after a runtime
   restart;
2. online-only action denial while disconnected;
3. fail-closed storage, malformed snapshot, duplicate-ID, and queue-bound
   behavior;
4. serialized concurrent writes without lost updates or duplicate IDs;
5. ordered reconnection delivery and durable acknowledgement removal;
6. retention after transport failure; and
7. reuse of the same event ID when delivery succeeded but its local
   acknowledgement checkpoint initially failed.

The checked-in Maestro flow `apps/metis/mobile/e2e/flows/offline-expo-go.yaml`
covers the intended Android airplane-mode path: disconnect, record an
offline-safe Downloads action, restart Expo Go without clearing data, assert the
pending event survived, then restore networking.

## Android execution boundary

The new airplane-mode flow could not reach an application assertion on this
host. Two Android 15 API 35 images were attempted headlessly under software TCG
because `/dev/kvm` is absent:

- `oshun_atd_api35` reached `sys.boot_completed=1`, but Android's package,
  settings, and activity services disappeared as `system_server` restarted
  before Expo Go could be prepared.
- `oshun_pixel_api35` connected over ADB and exposed a stable package service
  for several minutes, then reproduced the same regression before
  `sys.boot_completed` was ever set.

Both failures occurred before installing, launching, or asserting against the
Metis application. They are therefore invalid infrastructure runs, not failed
application tests. No passing airplane-mode JUnit result is claimed. The
existing critical learner smoke result remains separately documented in
`V9-004-MOBILE-E2E-EXECUTION-ATTEMPT.md`.

## Verification

- `pnpm --dir apps/metis/mobile test --runInBand`: 3 suites, 21 tests passed.
- `pnpm --dir apps/metis/mobile lint`: passed.
- `pnpm --dir apps/metis/mobile typecheck`: passed.
- `pnpm --dir apps/metis/mobile build`: Expo web export passed, producing the
  1,262-module bundle. Expo's generated native prebuild directories were removed
  after verification because this application does not track them.

## Honest boundary

This closes a repository-actionable slice of mobile/offline behavior: durable
local queuing, real connectivity transitions, restart-safe state, honest UI
status, unit/integration coverage, and an executable device flow. It does not
close the composite V9-004 launch checkbox. Authenticated server delivery,
conflict semantics, a stable airplane-mode device run, packaged release
installability, localization at scale, embodied face behavior, V2–V8 game
bridges, and creator payouts remain open.
