refactor(backup): simplify reminder engine to posture cadences

The engine asked one question in several voices and tracked state it did
not need. It now answers "could you get your money back?" with one verb
per posture.

Delete the balance-tier machinery (BackupBalanceTier, the 1,000,000-sat
tier, highestHandledBalanceTier) and the pending-action bookkeeping. The
record is now the acknowledgement time plus a one-time milestone flag;
keys written by the earlier shape are ignored rather than rejected, so no
migration is needed for an unreleased feature.

Make the cadence posture-dependent: 90 days for a vault-only wallet,
365 for one that already holds words. Anchor the schedule on the clock of
the thing being urged rather than on the most recent backup of any kind —
a both-backups wallet with a fresh vault and a two-year-old physical test
was never reminded, which was the whole point of the reminder.

Fire the 10,000,000-sat notice at most once per wallet, inclusive of the
threshold, retired by either dismissing it or acting on it. Merge the
both-backups posture into "test your backup" and drop the "review your
backups" nag, which named no action. There is deliberately no vault or
PIN freshness reminder: the fix for a single server-dependent recovery
path is a physical backup, not a PIN rehearsal.

The popup now asks one question and offers one action, with a
low-emphasis dismissal that snoozes a full cycle and never records a test
the app did not observe.

Author: FrancisPouliot

docs/backup-health-reminders.md

@@ -1,42 +1,57 @@
 # Backup health reminders
 
-Backup health reminders encourage users to periodically confirm that their wallet can still be recovered. They supplement the existing no-backup warning; they do not replace it.
+Every backup surface answers one question: **if this phone vanished right now, could you get your money back?** Each state has exactly one honest answer and exactly one thing to do about it.
+
+| Situation | Honest answer | The one action |
+| --- | --- | --- |
+| Nothing backed up | No — the money is gone | Back up, urgently |
+| Encrypted Vault only | Probably — it needs the server up and your PIN | Add a physical backup |
+| Physical backup done (with or without a vault) | Yes — if the words are still findable and correct | Occasionally confirm that is still true |
+
+## One surface per state
+
+Three surfaces, three tenses, no overlap:
+
+- the **every-launch warning** (`backup_warning_overlay.dart`) means "you are unprotected right now". Zero-backup only, unchanged by this feature.
+- the **reminder popup** means "it has been a while, or something changed". Every posture except zero-backup.
+- the **Backup Settings hero** means "here is your standing situation". Always available on the screen you visit deliberately.
+
+So zero backup gets the warning and the hero, never the popup; every other state gets the popup and the hero, never the warning. One popup asks one question and offers one action.
 
 ## Reminder matrix
 
-The reminder is evaluated for the default mainnet hot-wallet seed after at least one backup method has been verified. Eligible balances are aggregated separately as described below.
+The reminder is evaluated for the default mainnet hot-wallet seed once at least one backup method has been verified.
 
-| Verified backup posture | Reminder message | Primary action | Secondary action |
-| --- | --- | --- | --- |
-| No verified backup | No quarterly reminder. Existing no-backup warning behavior remains unchanged. | Existing backup flow | Existing dismissal behavior |
-| Recoverbull only | Explain that automatic recovery normally depends on the Recoverbull key server and recommend an independent physical backup. | Create and test a physical backup | Acknowledge the dependency risk |
-| Physical only | Ask the user to perform a health check of the physical backup they already have. Recoverbull is available only through a neutral link to other backup options. | Test the physical backup | Remind in three months |
-| Recoverbull and physical | Ask the user to review and test their available backups. | Review backup options | Remind in three months |
+| Verified backup posture | Reminder | Action |
+| --- | --- | --- |
+| No verified backup | None. The existing no-backup warning owns this state. | — |
+| Encrypted Vault only | Every 90 days: without a physical backup you cannot recover if the vault server is unavailable. | Add a physical backup |
+| Physical backup, with or without a vault | Every 365 days since the physical backup was last tested. | Test the backup |
 
-The reminder is shown only on the wallet home screen and only after higher-priority no-backup and legacy-storage warnings are clear.
+There is deliberately **no vault-freshness or PIN reminder**. A vault-only wallet's real exposure is depending on someone else for its only recovery path, and the fix for that is a physical backup, not a PIN rehearsal. Once a physical backup exists, PIN rot cannot cost the user their money.
 
-## Timing and balance milestones
+## Timing
 
-A scheduled reminder becomes due 90 full days after the most recent of:
+A scheduled reminder is anchored on the clock of the thing being urged:
 
-- the latest completed physical backup;
-- the latest completed Recoverbull backup; or
-- the last time the user acknowledged the reminder.
+- vault only — the latest vault backup, or the last acknowledgement;
+- physical backup present — the latest *physical* backup test, or the last acknowledgement. A fresh vault does not buy silence about words that were last read two years ago.
 
-A verified backup record with no completion timestamp is treated as due immediately. Acknowledging a reminder starts a new 90-day interval.
+A verified backup with no completion timestamp is due immediately.
 
-Balance milestones can show the reminder before the scheduled date:
+Dismissing a reminder snoozes it for a full cycle (90 or 365 days). It never writes a tested timestamp, so the Backup Settings screen keeps saying how long ago the backup was really tested while the popup is quiet. Only completing a verification flow resets that date; creating a backup counts as tested on day zero, because the creation flow tests it.
 
-- more than 1,000,000 sats; and
-- more than 10,000,000 sats after the first milestone has been handled.
+The popup is shown on the wallet home screen only, and only once the higher-priority no-backup and legacy-storage warnings are clear. A deep link or payment intent lands on its own route, so nothing ever stands between a payment and its completion.
 
-The comparisons are strict: exactly 1,000,000 or 10,000,000 sats does not trigger a milestone. Each milestone is recorded after the user acknowledges the reminder or completes the selected backup action, so ordinary balance fluctuations do not repeatedly trigger it.
+## Balance milestone
 
-Starting a backup action records a pending action. On the next evaluation, a backup completion timestamp at or after the action start handles the associated balance milestone. Cancelling the flow leaves the milestone due for the next app session.
+The first time an evaluation observes an eligible balance of **10,000,000 sats or more**, the reminder is shown once, whatever the schedule says, with the posture-appropriate ask. The comparison is inclusive: exactly 10,000,000 sats counts.
+
+That notice is retired for the lifetime of the wallet as soon as the user either dismisses it or acts on it. A balance later dropping below the threshold and crossing it again changes nothing — a wallet is told once.
 
 ## Eligible wallets and balances
 
-Only mainnet wallets whose keys are held on the device participate in reminder evaluation and balance milestones.
+Only mainnet wallets whose keys are held on the device participate in reminder evaluation and in the balance total.
 
 Included:
 
@@ -65,15 +80,21 @@ The overlay evaluates when wallet data or the Ark balance changes, after its fir
 
 Reminder state is stored locally in a versioned SharedPreferences record keyed by master fingerprint. It contains only:
 
-- the last acknowledgement time;
-- the highest handled balance tier;
-- a pending action start time; and
-- the pending action balance tier.
+- the last acknowledgement time; and
+- whether the balance milestone has been shown.
 
-No mnemonic, seed, private key, vault key, or other secret is stored or logged by the reminder. Malformed, unsupported, or unreadable reminder records are replaced with an empty in-memory record, which favors showing another reminder over suppressing one indefinitely. The underlying read failure is logged without exposing it to the user.
+No mnemonic, seed, private key, vault key, or other secret is stored or logged by the reminder. Keys written by an earlier shape of the record are ignored rather than rejected. Malformed, unsupported, or unreadable records are replaced with an empty in-memory record, which favors showing another reminder over suppressing one indefinitely. The underlying read failure is logged without exposing it to the user.
 
 If a reminder action cannot be persisted, the overlay stays visible so the user can retry. A localized "close for now" action is then available as a session-only escape; it does not acknowledge the reminder, so the app evaluates it again on the next launch.
 
+## Backup Settings screen
+
+The screen is composed top to bottom as status rows, then at most one hero, then the settings menu:
+
+1. **Status rows** — Physical Backup and Encrypted Vault, each Tested or Not tested, with a muted "Last tested …" line under a tested physical backup.
+2. **Hero** — the single most useful action right now, or nothing at all: an urgent *Back up your wallet* card when nothing is backed up, *add a physical backup* for a vault-only wallet, *test your backup* once the physical test is over a year old, and no card when the physical backup is fresh. The hero derives its posture from the same domain code the reminder uses, so the two can never disagree.
+3. **Menu** — Encrypted vault settings, Labels, Transaction History, plus the vault-key and test-backup entries when they apply. There is no "Start Backup" row: the zero-backup hero is the way in.
+
 ## Architecture
 
 The feature follows the repository flow described in `ARCHITECTURE.md`:
@@ -86,7 +107,7 @@ The repository boundary uses a domain entity and a separate persistence model. R
 
 ## Tests
 
-The focused suite covers the posture matrix, exact 90-day boundary, strict balance thresholds, testnet and non-local-signer exclusions, pending actions, persistence corruption, physical completion, and Recoverbull completion ordering.
+The focused suite covers the posture matrix, both cadences and their exact boundaries, the anchor rule (a fresh vault must not silence a stale physical backup), the inclusive milestone threshold and its once-per-wallet guarantee, dismissal snoozing without recording a test, testnet and non-local-signer exclusions, persistence corruption, and each hero the screen can render.
 
 Run it with:
 

lib/features/backup_settings/data/models/backup_health_reminder_model.dart

@@ -3,30 +3,22 @@ import 'package:bb_mobile/features/backup_settings/domain/backup_health_reminder
 class BackupHealthReminderModel {
   final int version;
   final int? lastAcknowledgedAtMillis;
-  final String highestHandledBalanceTier;
-  final int? pendingActionStartedAtMillis;
-  final String pendingActionBalanceTier;
+  final bool crossedTenMillionSats;
 
   const BackupHealthReminderModel({
     required this.version,
     required this.lastAcknowledgedAtMillis,
-    required this.highestHandledBalanceTier,
-    required this.pendingActionStartedAtMillis,
-    required this.pendingActionBalanceTier,
+    required this.crossedTenMillionSats,
   });
 
-  factory BackupHealthReminderModel.fromJson(
-    Map<String, dynamic> json,
-  ) => BackupHealthReminderModel(
-    version: _requiredInt(json, 'version'),
-    lastAcknowledgedAtMillis: _optionalInt(json, 'lastAcknowledgedAt'),
-    highestHandledBalanceTier: _requiredString(
-      json,
-      'highestHandledBalanceTier',
-    ),
-    pendingActionStartedAtMillis: _optionalInt(json, 'pendingActionStartedAt'),
-    pendingActionBalanceTier: _requiredString(json, 'pendingActionBalanceTier'),
-  );
+  /// Reads only the keys this record still has. Keys written by an earlier
+  /// shape of the feature are ignored rather than rejected.
+  factory BackupHealthReminderModel.fromJson(Map<String, dynamic> json) =>
+      BackupHealthReminderModel(
+        version: _requiredInt(json, 'version'),
+        lastAcknowledgedAtMillis: _optionalInt(json, 'lastAcknowledgedAt'),
+        crossedTenMillionSats: _optionalBool(json, 'crossedTenMillionSats'),
+      );
 
   factory BackupHealthReminderModel.fromEntity(
     BackupHealthReminderRecord record, {
@@ -36,43 +28,26 @@ class BackupHealthReminderModel {
     lastAcknowledgedAtMillis: record.lastAcknowledgedAt
         ?.toUtc()
         .millisecondsSinceEpoch,
-    highestHandledBalanceTier: record.highestHandledBalanceTier.name,
-    pendingActionStartedAtMillis: record.pendingActionStartedAt
-        ?.toUtc()
-        .millisecondsSinceEpoch,
-    pendingActionBalanceTier: record.pendingActionBalanceTier.name,
+    crossedTenMillionSats: record.crossedTenMillionSats,
   );
 
   Map<String, dynamic> toJson() => {
     'version': version,
     'lastAcknowledgedAt': lastAcknowledgedAtMillis,
-    'highestHandledBalanceTier': highestHandledBalanceTier,
-    'pendingActionStartedAt': pendingActionStartedAtMillis,
-    'pendingActionBalanceTier': pendingActionBalanceTier,
+    'crossedTenMillionSats': crossedTenMillionSats,
   };
 
   BackupHealthReminderRecord toEntity({required String masterFingerprint}) =>
       BackupHealthReminderRecord(
         masterFingerprint: masterFingerprint,
         lastAcknowledgedAt: _dateTimeFromMillis(lastAcknowledgedAtMillis),
-        highestHandledBalanceTier: _tierFromName(highestHandledBalanceTier),
-        pendingActionStartedAt: _dateTimeFromMillis(
-          pendingActionStartedAtMillis,
-        ),
-        pendingActionBalanceTier: _tierFromName(pendingActionBalanceTier),
+        crossedTenMillionSats: crossedTenMillionSats,
       );
 
   DateTime? _dateTimeFromMillis(int? milliseconds) => milliseconds == null
       ? null
       : DateTime.fromMillisecondsSinceEpoch(milliseconds, isUtc: true);
 
-  BackupBalanceTier _tierFromName(String name) {
-    for (final tier in BackupBalanceTier.values) {
-      if (tier.name == name) return tier;
-    }
-    return BackupBalanceTier.none;
-  }
-
   static int _requiredInt(Map<String, dynamic> json, String key) {
     final value = json[key];
     if (value is int) return value;
@@ -85,9 +60,10 @@ class BackupHealthReminderModel {
     throw FormatException('Invalid $key');
   }
 
-  static String _requiredString(Map<String, dynamic> json, String key) {
+  static bool _optionalBool(Map<String, dynamic> json, String key) {
     final value = json[key];
-    if (value is String) return value;
+    if (value == null) return false;
+    if (value is bool) return value;
     throw FormatException('Invalid $key');
   }
 }

lib/features/backup_settings/domain/backup_health_reminder.dart

@@ -1,65 +1,95 @@
-enum BackupHealthPosture { recoverbullOnly, physicalOnly, both }
+/// What a wallet can currently recover from.
+///
+/// There is no zero-backup value on purpose: that state is owned by the
+/// every-launch backup warning and by the Backup Settings hero, never by a
+/// reminder. [BackupHealthPosture.of] returns null for it.
+enum BackupHealthPosture {
+  recoverbullOnly,
+  physicalOnly,
+  both;
 
-enum BackupHealthTrigger { scheduled, balanceMilestone }
-
-enum BackupBalanceTier {
-  none,
-  oneMillion,
-  tenMillion;
+  /// How long the same advice waits before it is worth repeating.
+  ///
+  /// A vault-only wallet has a single recovery path that depends on someone
+  /// else, so it is asked more often than a wallet that already holds words.
+  Duration get reminderInterval => switch (this) {
+    BackupHealthPosture.recoverbullOnly => const Duration(days: 90),
+    BackupHealthPosture.physicalOnly ||
+    BackupHealthPosture.both => const Duration(days: 365),
+  };
 
-  bool isHigherThan(BackupBalanceTier other) => index > other.index;
+  /// Whether the one action for this posture is creating a physical backup,
+  /// as opposed to testing the physical backup that already exists.
+  bool get urgesPhysicalBackup => this == BackupHealthPosture.recoverbullOnly;
 
-  static BackupBalanceTier highest(
-    BackupBalanceTier first,
-    BackupBalanceTier second,
-  ) => first.index >= second.index ? first : second;
+  /// The posture for a set of verified backups, or null when nothing is
+  /// backed up.
+  static BackupHealthPosture? of({
+    required bool isEncryptedVaultTested,
+    required bool isPhysicalBackupTested,
+  }) => switch ((isEncryptedVaultTested, isPhysicalBackupTested)) {
+    (true, false) => recoverbullOnly,
+    (false, true) => physicalOnly,
+    (true, true) => both,
+    (false, false) => null,
+  };
 }
 
+enum BackupHealthTrigger { scheduled, balanceMilestone }
+
+/// Whether advice anchored at [anchor] is due again at [now].
+///
+/// A missing anchor (a backup marked tested without a completion date) and a
+/// clock that has moved backwards both count as due: repeating advice is
+/// better than silently stopping.
+bool isBackupReminderDue({
+  required DateTime? anchor,
+  required DateTime now,
+  required Duration interval,
+}) =>
+    anchor == null ||
+    anchor.isAfter(now) ||
+    !now.isBefore(anchor.add(interval));
+
 class BackupHealthReminderRecord {
   final String masterFingerprint;
   final DateTime? lastAcknowledgedAt;
-  final BackupBalanceTier highestHandledBalanceTier;
-  final DateTime? pendingActionStartedAt;
-  final BackupBalanceTier pendingActionBalanceTier;
+
+  /// Set once the user has been told, once per wallet lifetime, that the
+  /// balance reached the milestone. A balance dropping back below it never
+  /// clears this.
+  final bool crossedTenMillionSats;
 
   const BackupHealthReminderRecord({
     required this.masterFingerprint,
     this.lastAcknowledgedAt,
-    this.highestHandledBalanceTier = BackupBalanceTier.none,
-    this.pendingActionStartedAt,
-    this.pendingActionBalanceTier = BackupBalanceTier.none,
+    this.crossedTenMillionSats = false,
   });
 
   BackupHealthReminderRecord copyWith({
     DateTime? lastAcknowledgedAt,
-    BackupBalanceTier? highestHandledBalanceTier,
-    DateTime? pendingActionStartedAt,
-    bool clearPendingAction = false,
-    BackupBalanceTier? pendingActionBalanceTier,
+    bool? crossedTenMillionSats,
   }) => BackupHealthReminderRecord(
     masterFingerprint: masterFingerprint,
     lastAcknowledgedAt: lastAcknowledgedAt ?? this.lastAcknowledgedAt,
-    highestHandledBalanceTier:
-        highestHandledBalanceTier ?? this.highestHandledBalanceTier,
-    pendingActionStartedAt: clearPendingAction
-        ? null
-        : pendingActionStartedAt ?? this.pendingActionStartedAt,
-    pendingActionBalanceTier: clearPendingAction
-        ? BackupBalanceTier.none
-        : pendingActionBalanceTier ?? this.pendingActionBalanceTier,
+    crossedTenMillionSats: crossedTenMillionSats ?? this.crossedTenMillionSats,
   );
 }
 
 class BackupHealthDecision {
   final String masterFingerprint;
   final BackupHealthPosture posture;
   final BackupHealthTrigger trigger;
-  final BackupBalanceTier currentBalanceTier;
+
+  /// When the physical backup was last tested, when it has been. Null for a
+  /// vault-only wallet and for a tested backup with no recorded date; the UI
+  /// must not claim a test date the app never observed.
+  final DateTime? physicalBackupTestedAt;
 
   const BackupHealthDecision({
     required this.masterFingerprint,
     required this.posture,
     required this.trigger,
-    required this.currentBalanceTier,
+    this.physicalBackupTestedAt,
   });
 }

lib/features/backup_settings/domain/usecases/acknowledge_backup_health_reminder_usecase.dart

@@ -4,6 +4,10 @@ import 'package:bb_mobile/features/backup_settings/domain/backup_settings_failur
 import 'package:bb_mobile/features/backup_settings/domain/repositories/backup_health_reminder_repository.dart';
 import 'package:meta/meta.dart';
 
+/// Snoozes a reminder for a full cycle.
+///
+/// This never writes a tested timestamp: the Backup Settings screen keeps
+/// saying how long ago the backup was really tested while the popup is quiet.
 class AcknowledgeBackupHealthReminderUsecase {
   final BackupHealthReminderRepository _repository;
   final DateTime Function() _clock;
@@ -28,11 +32,9 @@ class AcknowledgeBackupHealthReminderUsecase {
     return _repository.save(
       record.copyWith(
         lastAcknowledgedAt: _clock().toUtc(),
-        highestHandledBalanceTier: BackupBalanceTier.highest(
-          record.highestHandledBalanceTier,
-          decision.currentBalanceTier,
-        ),
-        clearPendingAction: true,
+        crossedTenMillionSats:
+            record.crossedTenMillionSats ||
+            decision.trigger == BackupHealthTrigger.balanceMilestone,
       ),
     );
   }