Plan: Churn-risk retention push via BigQuery ML

docs/plans/churn-predictions.md

@@ -0,0 +1,43 @@
+# Plan — Churn-risk retention push
+
+- **Status:** Proposed
+- **Effort:** Medium
+- **Firebase services:** Analytics → BigQuery, BigQuery ML (or Firebase Predictions if available), Cloud Scheduler, Cloud Functions, FCM
+
+## Overview
+
+Identify users at risk of churn and trigger a James-voiced re-engagement push. Firebase Predictions is deprecated, so the modern path is BigQuery ML trained on the Analytics export.
+
+## Approach
+
+1. Depends on **Analytics → BigQuery export** plan.
+2. Create a BQ scheduled query that computes a simple churn feature set: `daysSinceLastClaim`, `totalClaims`, `friendsCount`, `streakLength`, `sessionsLast7d`.
+3. Train a logistic regression model with `CREATE MODEL ... OPTIONS(model_type='LOGISTIC_REG')` using a label defined as "did not return in next 7 days".
+4. Daily scheduled query writes predictions to `gs://.../churn-predictions/YYYY-MM-DD/`.
+5. Cloud Function `sendChurnPushes` reads the predictions, filters to `risk > 0.7 AND notificationPrefs.retentionEnabled`, and sends FCM messages.
+
+## Messages
+
+- James-voiced and specific: "Your streak's looking lonely without you, squire. A VR box in BS6 is waiting."
+- Never more than one retention push per user per 7 days.
+
+## Privacy
+
+- Predictions live only in BQ (PII already scrubbed per the Analytics plan).
+- Add an opt-out under `notificationPrefs.retentionEnabled` (default true).
+
+## Rollout
+
+- Ship the BQ model with monitoring first, no pushes.
+- Review prediction quality manually against actual return behaviour for 2 weeks.
+- Enable pushes to 10 % first, then ramp.
+
+## Risks
+
+- Small sample size → noisy model. Start simple; don't over-engineer.
+- Push fatigue; enforce frequency caps and quiet hours.
+
+## Testing
+
+- BQ model evaluation (AUC > 0.7 on held-out set) before enabling pushes.
+- Unit test the FCM dispatcher against a fake predictions file.

lib/claim.dart

@@ -125,11 +125,14 @@ class _ClaimState extends State<Claim> with TickerProviderStateMixin {
         postboxes[entry.key as String] =
             Map<String, dynamic>.from(entry.value as Map);
       }
+      // Cloud Functions serialise JS numbers as either int or double;
+      // assigning a double to a typed int field throws, so normalise via num.
+      int asInt(dynamic v) => (v as num?)?.toInt() ?? 0;
       setState(() {
-        _count = counts['total'] ?? 0;
-        _maxPoints = points['max'] ?? 0;
-        _minPoints = points['min'] ?? 0;
-        _claimedToday = counts['claimedToday'] ?? 0;
+        _count = asInt(counts['total']);
+        _maxPoints = asInt(points['max']);
+        _minPoints = asInt(points['min']);
+        _claimedToday = asInt(counts['claimedToday']);
         _postboxes = postboxes;
         currentStage = _count > 0 ? ClaimStage.results : ClaimStage.empty;
       });

lib/nearby.dart

@@ -113,23 +113,26 @@ class _NearbyState extends State<Nearby> {
       final claimedCompass = data['claimedCompass'] != null
           ? Map<String, dynamic>.from(data['claimedCompass'] as Map)
           : <String, dynamic>{};
+      // Cloud Functions serialise JS numbers as either int or double; assigning
+      // a double to a typed int field throws, so normalise every count via num.
+      int asInt(dynamic v) => (v as num?)?.toInt() ?? 0;
       setState(() {
-        _count = counts['total'] ?? 0;
-        _maxPoints = pts['max'] ?? 0;
-        _minPoints = pts['min'] ?? 0;
+        _count = asInt(counts['total']);
+        _maxPoints = asInt(pts['max']);
+        _minPoints = asInt(pts['min']);
         currentStage = NearbyStage.results;
         for (final dir in const [
           'N', 'NNE', 'NE', 'ENE', 'E', 'ESE',
           'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW',
           'W', 'WNW', 'NW', 'NNW',
         ]) {
-          _compassCounts[dir] = compass[dir] ?? 0;
-          _claimedCompassCounts[dir] = claimedCompass[dir] ?? 0;
+          _compassCounts[dir] = asInt(compass[dir]);
+          _claimedCompassCounts[dir] = asInt(claimedCompass[dir]);
         }
-        _claimedToday = counts['claimedToday'] ?? 0;
+        _claimedToday = asInt(counts['claimedToday']);
         for (final cipher in MonarchInfo.all) {
-          _cipherTotals[cipher] = counts[cipher] ?? 0;
-          _cipherClaimed[cipher] = counts['${cipher}_claimed'] ?? 0;
+          _cipherTotals[cipher] = asInt(counts[cipher]);
+          _cipherClaimed[cipher] = asInt(counts['${cipher}_claimed']);
         }
         _lastScanned = DateTime.now();
       });

lib/wear/wear_claim_page.dart

@@ -52,8 +52,10 @@ class _WearClaimPageState extends State<WearClaimPage> {
       });
       if (!mounted) return;
       final counts = result.data['counts'] ?? {};
-      final total = (counts['total'] as int?) ?? 0;
-      final claimed = (counts['claimedToday'] as int?) ?? 0;
+      // Cloud Functions serialise JS numbers as either int or double; `as int?`
+      // would throw on a double, so normalise via num.
+      final total = (counts['total'] as num?)?.toInt() ?? 0;
+      final claimed = (counts['claimedToday'] as num?)?.toInt() ?? 0;
       _postboxes = Map<String, dynamic>.from(result.data['postboxes'] ?? {});
       setState(() {
         _count = total;

lib/wear/wear_compass_page.dart

@@ -75,8 +75,13 @@ class _WearCompassPageState extends State<WearCompassPage> {
       final counts = result.data['counts'] ?? {};
       final compassRaw = result.data['compass'] ?? {};
       setState(() {
-        _totalCount = (counts['total'] as int?) ?? 0;
-        _compassCounts = Map<String, int>.from(compassRaw);
+        // Cloud Functions serialise JS numbers as either int or double;
+        // `as int?` would throw on a double, so normalise via num.
+        _totalCount = (counts['total'] as num?)?.toInt() ?? 0;
+        _compassCounts = {
+          for (final e in (compassRaw as Map).entries)
+            e.key as String: (e.value as num).toInt(),
+        };
         _stage = _CompassStage.results;
       });
       // Haptic pulse to signal scan complete.
@@ -206,7 +211,13 @@ class _WearCompassPageState extends State<WearCompassPage> {
               angle: -rotation,
               child: CustomPaint(
                 size: Size(size, size),
-                painter: FuzzyCompassPainter(sectors: sectorValues),
+                // Pass rotation so the painter counter-rotates the 'N' label;
+                // otherwise it spins with the canvas and is unreadable whenever
+                // the watch is not pointing north.
+                painter: FuzzyCompassPainter(
+                  sectors: sectorValues,
+                  rotation: rotation,
+                ),
               ),
             ),
             // Centre count overlay (doesn't rotate)

lib/wear/wear_status_page.dart

@@ -18,10 +18,14 @@ class WearStatusPage extends StatefulWidget {
 class _WearStatusPageState extends State<WearStatusPage> {
   final StreakService _streakService = StreakService();
   late final Stream<int?> _streakStream = _streakService.streakStream();
+  // Cache so the StreamBuilder doesn't re-subscribe (and briefly show empty
+  // stats) on every rebuild. Computed once in initState from the uid at mount.
+  late final Stream<DocumentSnapshot<Map<String, dynamic>>>? _userDocStream =
+      _buildUserDocStream();
 
   String? get _displayName => FirebaseAuth.instance.currentUser?.displayName;
 
-  Stream<DocumentSnapshot<Map<String, dynamic>>>? _userDocStream() {
+  Stream<DocumentSnapshot<Map<String, dynamic>>>? _buildUserDocStream() {
     final uid = FirebaseAuth.instance.currentUser?.uid;
     if (uid == null) return null;
     return FirebaseFirestore.instance.collection('users').doc(uid).snapshots();
@@ -71,7 +75,7 @@ class _WearStatusPageState extends State<WearStatusPage> {
 
               // Lifetime points
               StreamBuilder<DocumentSnapshot<Map<String, dynamic>>>(
-                stream: _userDocStream(),
+                stream: _userDocStream,
                 builder: (context, snap) {
                   final data = snap.data?.data();
                   final lifetimePoints =