nowMsClamped function

int nowMsClamped([ StorageService? storage ])

Current millisecond timestamp, clamped to never go below the largest value seen so far.

Reads/writes the ambient StorageService.to singleton by default. Pass storage explicitly for a class that holds its own injected StorageService instance instead of going through the global singleton (e.g. VersionedJsonStore) — using the wrong instance here would clamp against a different watermark than the one the caller actually persists its own data through.

Implementation

int nowMsClamped([StorageService? storage]) {
  final store = storage ?? StorageService.to;
  final current =
      DateTime.now().toUtc().millisecondsSinceEpoch + _debugTimeOffsetMs;
  final maxSeen = store.getInt(StorageKeys.maxMsSeen);
  if (current > maxSeen) {
    store.setInt(StorageKeys.maxMsSeen, current);
    return current;
  }
  // BUG-48: `current == maxSeen` (same millisecond re-read, or — far more
  // commonly for the day-granularity sibling below — a second call the
  // same day) is NOT a rewind attempt; only `current < maxSeen` is.
  if (current < maxSeen) clockRewindBlockedCount++;
  return maxSeen;
}