gen5 link conformance: official bootstrap, a real burst count gate, command correlation

lib/compute/derivation_engine.dart

@@ -1317,8 +1317,19 @@ const int kAlgoVersion = 76;
 // which re-orders a float summation — that is computed before the sort now, and
 // the real overnight capture staged identically down to the last digit of
 // confidence.
+//
+// The protocol repin to b7990e1 also holds at 76, and this one is checkable
+// rather than argued: diff the two pins and the gen4 record decoder
+// (`lib/src/records.dart`) is untouched, as is every gen4 line in the package
+// export. What moved is the gen5 surface — the hello map, the control plane,
+// the command surface and the v18/v20/v22/v26 field maps — plus their tests.
+// For anyone on a gen4 strap every number out of this package is byte-identical
+// across the repin, so a bump would invalidate every stored day to recompute
+// the same answers. The gen5 records it adds are new: no released build could
+// decode them, so no stored day at v76 was derived from one, and there is
+// nothing for a same-version serve to confuse.
 const String kAnalyticsPin = 'd9362a66fbeac326d5d7d7b1fe27b28e41169a79';
-const String kProtocolPin = 'c761f29bcbed73886b1b059dcd9e92e4333574f5';
+const String kProtocolPin = 'b7990e1499f9ae83dbd4c1fa8481dbe8413e7337';
 
 // Fold idempotency, the minimum-nights warm-up, and legacy-payload handling
 // all live in SleepProfilePolicy (pure, unit-tested) — see

lib/data/db.dart

@@ -250,7 +250,7 @@ class LocalDb {
   /// pass it: sqflite throws `ArgumentError('onCreate must be null if no
   /// version is specified')` BEFORE opening anything when `onCreate` is given
   /// without `version` (sqflite_common database_mixin.dart).
-  static const int schemaVersion = 45;
+  static const int schemaVersion = 46;
 
   /// SQLite caps host parameters per statement (`SQLITE_MAX_VARIABLE_NUMBER` —
   /// only 999 on the builds shipped with older Android/iOS). Any `IN (?, ?, …)`
@@ -766,6 +766,14 @@ class LocalDb {
           await _ensureBandBatteryChargeUnits(db);
           await _backfillBandBatteryFromEvents(db);
         }
+        if (oldV < 46) {
+          // Retire the disproven gen5 columns that v34-era dev builds banked
+          // (`on_wrist` / `hr_valid`, plus the -50.00 °C skin-temp sentinel).
+          // Data-only: the DDL is untouched, so this does NOT diverge an
+          // upgraded install's schema from a fresh one. See
+          // _retireDisprovenOneHzColumns for the evidence.
+          await _retireDisprovenOneHzColumns(db);
+        }
       },
       onOpen: (db) async {
         await _repairOpenSchema(db);
@@ -1029,6 +1037,40 @@ class LocalDb {
   static Future<void> _ensureBeatTimeColumn(Database db) =>
       _addColumnIfMissing(db, 'decoded_rr', 'beat_ts_ms', 'INTEGER');
 
+
+  /// v46: retire what v34 banked into `on_wrist` / `hr_valid`, and any
+  /// `skin_temp_c` that is really the sensor's unavailable sentinel.
+  ///
+  /// v34 filled `on_wrist` from gen5 v18 body 60 bits 0-1 and `hr_valid` from
+  /// body 15 bit7. Both readings are disproven: bits 0-1 are the primary-flags
+  /// bit-8 snapshot (not wear), and bit7 toggles ~50/50 independently of HR
+  /// presence across 1,587,671 retained records (not validity). `skin_temp_c`
+  /// could likewise hold the AS6221 -50.00 °C unavailable/error code, which is
+  /// not a temperature. The writer stopped emitting all three
+  /// (`sampleFromGen5Historical`); this clears what it already stored, so no
+  /// future reader can pick up a confident answer the data never supported.
+  ///
+  /// DDL-NEUTRAL on purpose: the columns stay, nullable, exactly as v34 created
+  /// them, so a fresh install and an upgraded one still end at the same schema
+  /// (the fields remain the right shape should an honest source ever appear).
+  /// Idempotent — a second run matches no rows. Cheap enough for the iOS
+  /// open-database watchdog: `decoded_onehz` is bounded by `rawRetentionDays`,
+  /// this is one scan, and it writes only the rows that carry a value.
+  static Future<void> _retireDisprovenOneHzColumns(Database db) async {
+    final have = await _columnsOf(db, 'decoded_onehz');
+    // Pre-v34 tables never had the columns; nothing to retire.
+    if (!have.contains('on_wrist')) return;
+    await db.execute(
+      'UPDATE decoded_onehz SET '
+      'on_wrist = NULL, '
+      'hr_valid = NULL, '
+      'skin_temp_c = CASE WHEN skin_temp_c <= -49.995 THEN NULL '
+      'ELSE skin_temp_c END '
+      'WHERE on_wrist IS NOT NULL OR hr_valid IS NOT NULL '
+      'OR skin_temp_c <= -49.995',
+    );
+  }
+
   static Future<void> _ensureDayResultSkippedColumn(Database db) =>
       _addColumnIfMissing(
         db,
@@ -3263,6 +3305,12 @@ class LocalDb {
     // optical/thermal ADCs at all, so those three are ALWAYS absent there.
     // Absence now lands as NULL. `_relaxDecodedSensorNulls` (v39) rebuilds the
     // table on existing installs.
+    // `on_wrist` and `hr_valid` currently have NO honest writer at all — the
+    // gen5 v18 bits once mapped onto them are disproven (see
+    // `sampleFromGen5Historical` and _retireDisprovenOneHzColumns), so every
+    // row written since that mapping change stores NULL. The columns are kept, nullable and
+    // correctly shaped, for a source that can actually supply them; they are
+    // NOT a place to park a plausible-looking bit.
     await _ensureDecodedOneHzBandFields(db);
     // NO index on `counter`. There was one, described as a forensic-only
     // lookup — and nothing in the app ever filtered or ordered by `counter`
@@ -3780,9 +3828,11 @@ class LocalDb {
             stepCount: g.stepMotionCounter,
             stepCadence: g.stepCadence,
             activityClass: g.activityClassKnown,
-            skinTempC: g.skinTempC,
-            onWrist: g.onWristRaw,
-            hrValid: g.hrRrValidThisSecond,
+            // Same honesty contract as the live mapper: the -50.00 °C code is
+            // the sensor's unavailable sentinel, and body-60 bits 0-1 / body-15
+            // bit7 are disproven as wear / HR-validity (see
+            // sampleFromGen5Historical) — a replay must not resurrect them.
+            skinTempC: g.skinTempCOrNull,
             hrAlt: g.heartRateAlt,
             // MT-12's three columns exist (v43) and the write below names
             // them. Carried here because they are free and the point of
@@ -6400,6 +6450,19 @@ class LocalDb {
                     if (cols.contains(e.key)) e.key: e.value,
                 };
                 if (row.isEmpty) continue;
+                if (t == 'decoded_onehz') {
+                  // A pre-v46 export still carries the retired columns as
+                  // VALUES (the disproven on_wrist/hr_valid reads and the
+                  // -50.00 °C skin-temp error sentinel). Importing them
+                  // verbatim would reinstate exactly the rows the v46
+                  // data-retirement cleaned, so the same rule applies at this
+                  // boundary — the migration only runs on version bumps and
+                  // never sees imported rows.
+                  if (cols.contains('on_wrist')) row['on_wrist'] = null;
+                  if (cols.contains('hr_valid')) row['hr_valid'] = null;
+                  final st = row['skin_temp_c'];
+                  if (st is num && st <= -49.995) row['skin_temp_c'] = null;
+                }
                 if (t == 'day_result') {
                   if (protectedKeys.contains(
                     '${row['day_id']}|${row['algo_version']}',

lib/data/models.dart

@@ -40,15 +40,26 @@ class Sample {
   /// baseline before it means anything) this is usable on its first second.
   final double? skinTempC;
 
-  /// The band's own on-wrist determination for this second (2-bit code).
+  /// The band's own on-wrist determination for this second, if a decoder can
+  /// ever honestly supply one. **Nothing supplies it today** — gen4 has no such
+  /// field, and the gen5 v18 bits once read as wear (body 60 bits 0-1) are the
+  /// primary-flags bit-8 snapshot, disproven as a wear signal. Wear truth lives
+  /// in the HELLO body, the wrist on/off events and the wear-gated streams, not
+  /// in a per-second column. Do not re-wire those bits here; see
+  /// `sampleFromGen5Historical`.
   final int? onWrist;
 
-  /// The band's own "HR and RR are valid this second" flag.
+  /// The band's own "HR and RR are valid this second" flag, if a decoder can
+  /// ever honestly supply one. **Nothing supplies it today** — gen5 v18's
+  /// body-15 bit7 was disproven as a validity flag on 1.59M retained records
+  /// (it toggles ~50/50 independently of HR presence). HR presence is read off
+  /// [hr] itself (the decoders already gate it to 25..230, and readers use
+  /// `hr > 0`), never from this column.
   final bool? hrValid;
 
   /// A second heart-rate byte the band reports alongside [hr]. It CORROBORATES
-  /// [hr] (agreement runs ~58-75%, best when [hrValid]); it is not a substitute
-  /// heart rate and must never be displayed as one.
+  /// [hr] (agreement runs ~58-75%); it is not a substitute heart rate and must
+  /// never be displayed as one.
   final int? hrAlt;
 
   /// Ambient-light ADC count — GEN4 ONLY (gen5 sends no per-second equivalent).

lib/state/app_state.dart

@@ -3355,6 +3355,18 @@ class AppState extends ChangeNotifier {
   }) async {
     var last = SyncReport(0, 0, false);
     for (var i = 0; i < maxSessions && engine.isConnected; i++) {
+      // Terminal `Stuck`: a burst failed validation
+      // 15 times and the abort went out, so this connection's history is over.
+      // The engine refuses every further drain trigger, but stopping here too
+      // keeps the loop from spending its remaining sessions waiting out an idle
+      // timeout apiece against a link that will never answer.
+      if (engine.historyStuckThisSession) {
+        _log(
+          'Backfill stop — history is terminal (Stuck) for this connection; '
+          'the band keeps its checkpoint until the next one.',
+        );
+        break;
+      }
       // rec_ts_hw, not lastDecodedRecTs() — see the boot-time seed above for
       // why: an R10-lite-heavy backlog can genuinely advance without ever
       // touching decoded_onehz, and this "did we make progress" check must
@@ -3615,8 +3627,13 @@ class AppState extends ChangeNotifier {
     if (armed == null) {
       // Do NOT persist or start the confirmation machine, or we'd strand a
       // phantom alarm "waiting for the strap to confirm" that can never fire.
-      _log('[alarm] arm write FAILED — not persisting; alarm not set.');
-      throw Exception('Alarm not sent — the strap did not accept the write');
+      // Null now covers two cases: the write never left the phone, and the
+      // strap answered and REFUSED the alarm. Both mean the band holds no alarm, so both
+      // must stay out of persistence; the engine log says which one it was.
+      _log('[alarm] the band did not take the alarm — not persisting.');
+      // Neutral on purpose: null covers both a write that never left the
+      // phone and an explicit refusal — the engine log says which.
+      throw Exception('Alarm not set');
     }
     final epoch = armed.millisecondsSinceEpoch ~/ 1000;
     _savedAlarm = epoch;

pubspec.lock

@@ -933,8 +933,8 @@ packages:
     dependency: "direct main"
     description:
       path: "."
-      ref: c761f29bcbed73886b1b059dcd9e92e4333574f5
-      resolved-ref: c761f29bcbed73886b1b059dcd9e92e4333574f5
+      ref: b7990e1499f9ae83dbd4c1fa8481dbe8413e7337
+      resolved-ref: b7990e1499f9ae83dbd4c1fa8481dbe8413e7337
       url: "https://github.com/OpenStrap/protocol.git"
     source: git
     version: "1.0.0"

pubspec.yaml

@@ -74,7 +74,12 @@ dependencies:
       # Repinned to the #27 head after its own review pass. NO kAlgoVersion
       # bump: the fixes only reject NaN/±inf, which was never a measurement, so
       # for any user whose data is valid the output is byte-identical.
-      ref: c761f29bcbed73886b1b059dcd9e92e4333574f5
+      #
+      # REPIN (this branch): protocol main @ b7990e1, the #31 merge commit.
+      # #31 carries the gen5 hello map, the real clock opcodes and the v18
+      # record field map this branch's decoders need. main's pre-gen5 pin is
+      # deliberate THERE; this is the branch that wants gen5.
+      ref: b7990e1499f9ae83dbd4c1fa8481dbe8413e7337
   openstrap_analytics:
     git:
       url: https://github.com/OpenStrap/analytics.git

test/absence_and_offload_guards_test.dart

@@ -92,32 +92,6 @@ void main() {
     });
   });
 
-  group('BurstShortfallGate — bounded, because always-FAIL wedged sync', () {
-    test('the first short burst is refused, the redelivery is not', () {
-      final g = BurstShortfallGate();
-      expect(g.refuse('aa'), isTrue);
-      expect(g.refuse('aa'), isFalse,
-          reason: 'a stable token must never ping-pong');
-    });
-
-    test('a fresh token in the same session is still capped', () {
-      final g = BurstShortfallGate();
-      expect(g.refuse('aa'), isTrue);
-      // A band re-issuing a NEW token for the same data would defeat the
-      // per-token bound; the per-session budget catches it.
-      expect(g.refuse('bb'), isFalse);
-    });
-
-    test('a new session refills the session budget but not the run total', () {
-      final g = BurstShortfallGate(maxPerSession: 1, maxTotal: 2);
-      expect(g.refuse('a'), isTrue);
-      g.onSessionStart();
-      expect(g.refuse('b'), isTrue);
-      g.onSessionStart();
-      expect(g.refuse('c'), isFalse, reason: 'run total is the backstop');
-      expect(g.refusalsTotal, 2);
-    });
-  });
 
   group('TrimAckPolicy — the shortfall refusal is last, and only post-commit',
       () {