gemstone-nexus · Phase 6
GS-MOB-01 — GemStone Mobility Layer
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 43 | GS-MOB-01 | GS-MOB-01 — GemStone Mobility Layer | mobility | DevResources/docs/GS-MOB-01.md | This document is the executable Mobility Layer specification named by DOCA2, DOC02 Phases 2B/2C, DOC03 Section 13, and DOC06 Section 7. It replaces the superseded React Native/Expo/PWA mobile stack with Capacitor as the sole mobile client. | 6bacfd2c410d72785a1de99eedb66e4b55ada5a3 | 2026-07-22 18:33:18 |
Content
# GS-MOB-01 — GemStone Mobility Layer
*Field Mode, Extended Sessions, native audio bridge, and wake-word*
**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Approved for Build · **Date:** July 21, 2026
## 1. Purpose
This document is the executable Mobility Layer specification named by DOCA2, DOC02 Phases 2B/2C, DOC03 Section 13, and DOC06 Section 7. It replaces the superseded React Native/Expo/PWA mobile stack with Capacitor as the sole mobile client.
## 2. Client Stack
- React + Vite web app wrapped by Capacitor (`@capacitor/*` current major aligned with the prior StackOne Capacitor seed).
- Strict DataRightTailwind for all UI.
- Capacitor is first-class: web, Android, and iOS ship via atomic concurrency; a Capacitor fail is a feature fail.
- Auth0 Universal Login with Google, Facebook, and LinkedIn social connections; roles map to DOC03 Section 7.
## 3. Modes
| Mode | Intent | Audio path |
| --- | --- | --- |
| Field Mode | Foreground tap-to-talk for brief field interactions | Capacitor WebView: `getUserMedia` / `MediaRecorder` |
| Extended Session | Hands-free / longer sessions (Didymus, research, planning) | Native background audio bridge |
Do not merge these into a single audio implementation.
## 4. Field Mode (Phase 2B)
Requirements:
- Single large center-screen tap target; voice capture starts within 1 second of tap (DOC02 / DOC04 US-11).
- Ascending dual-tone chime confirms capture start.
- Heads-Up UI must remain legible in direct sunlight (manual outdoors check).
- Recents list restores at least 20 prior sessions via scroll-and-select.
- No native microphone plugin required for Field Mode.
Gate criteria: DOC02 Section 6.5.
## 5. Extended Sessions (Phase 2C)
Requirements:
- Native background audio entitlements:
- iOS: `AVAudioSession` with `UIBackgroundModes: audio`
- Android: foreground service with `FOREGROUND_SERVICE_TYPE_MICROPHONE` and persistent notification
- Periodic mic-open cue at configured interval.
- Approaching extended timeout requires explicit confirmation before mic close; confirmed timeout transitions session to ENDED (not RESUMABLE).
- Android is priority platform; iOS follows once Android is proven.
Gate criteria: DOC02 Section 6.6.
## 6. Interruption and Resume
Canonical interruption causes (aligned with DOC03 Section 5 and DOC13 Section 4):
1. OS audio focus loss (including incoming call)
2. Network drop
3. App backgrounding
Path:
```
ACTIVE -> PAUSED (interruption_snapshot written)
-> RESUMABLE (session-ready chime)
-> ACTIVE (one tap or app reopen; restore via Atlas Vault)
```
Resume behavior must be identical across the three causes (DOC04 US-02). Snapshot must be non-null before PAUSED is durable (DOC08 Section 1).
## 7. Wake-Word
- Configurable multi-phrase list via `WAKE_PHRASES` (DOC06).
- Android: on-device model in a foreground service; activation from fully killed app state in at least 8 of 10 quiet-room trials.
- iOS: Siri Shortcuts path; launch and listen in at least 9 of 10 trials.
- Android default-assistant (`VoiceInteractionService`) is out of scope for Phase 1 (DOC02 Section 3).
## 8. Acoustic Feedback Framework
| Event | Feedback |
| --- | --- |
| Field Mode capture start | Ascending dual-tone |
| Extended Session mic still open | Periodic unobtrusive cue |
| Session-ready (RESUMABLE) | Session-ready chime |
| Transcription / vectorization failure | In-app notification + system log within 5 minutes |
## 9. Audio Retention Policy
- Capture begins the moment the mic opens; no ambiguous pre-buffer state.
- Raw audio is discarded immediately after transcription, indexing, and vectorization into Atlas Vault.
- On pipeline failure, hold audio in chunks; dual-flag in-app and system log; do not discard until vectorization succeeds (DOC03 Section 14, DOC08 Section 4).
- No session transcripts or audio to external APIs; AES-256 at rest, TLS 1.3 in transit.
## 10. Native Audio Bridge Architecture
```
Capacitor JS layer
|-- Field Mode --> WebView media APIs
|-- Extended Session --> Capacitor plugin bridge
|-- iOS: AVAudioSession + background audio mode
|-- Android: mic foreground service + notification
|-- Wake-word --> Android FG service model / iOS Siri Shortcut
|-- Session control --> WebSocket /api session resume endpoints
```
Plugin surface must expose: start/stop capture, interruption callbacks (focus loss, network, background), cue scheduling, and wake-word enable/disable. Implementation detail may evolve; the mode split and interruption contract may not.
## 11. Store and Entitlement Notes
- Follow Apple background-audio guidelines; avoid patterns resembling always-on ambient listening.
- Play/App Store submission packages are Phase 5 deliverables (DOC02 Section 6.10).
- WCAG AA for the mobile UI is a Phase 4 gate.
## 12. Platform status (Phase 2B/2C build)
| Surface | Status |
| --- | --- |
| Field Mode (web + Capacitor WebView) | Implemented — `/app/field`, dual-tone, Recents ≥20 API |
| Extended Session Android FG mic service | Implemented scaffold — `ExtendedAudioService` + plugin |
| Extended Session iOS AVAudioSession | Scaffold — `Info.plist` background audio + Swift plugin (needs macOS/Xcode) |
| Wake-word Android FG service | Scaffold armed (notification + service); on-device model + 8/10 device trials pending |
| Wake-word iOS Siri Shortcuts | Scaffold only — App Intent wiring needs macOS; 9/10 device trials pending |
| Linux / Windows | Field Mode only; Extended/wake use web fallbacks (documented, not device gates) |
| HorizonORBIT login | Out of scope for mobility — Auth0 stub retained |
Device QA gates in DOC02 §6.5 / §6.6 (sunlight check, call interruption 10-trial, wake-word trials) remain practitioner/QA sign-off on hardware.
---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505