TrustedClockService class

A rewind-proof clock that RECOVERS from a suspicious forward jump instead of permanently locking onto it (IDEA-40) — the failure mode utils/clamped_clock.dart's plain watermark clamp has: once a forward jump (deliberate or an honest clock misconfiguration) bumps the watermark to some far-future instant, every time-gated system it backs stays locked until the REAL wall clock naturally catches up to that instant — which, for a big jump, can be months or years.

The fix: a ClockJudgement.suspiciousForwardJump sample never advances the trusted baseline. Only ClockJudgement.normal (and a forward-moving ClockJudgement.reboot) samples do. So the worst case after an honest "oops, changed my clock" moment is a short wait for the real clock to pass the baseline again — not a wait for it to pass the bogus jumped value.

Deliberately out of scope for this class (kept as a smaller, safer surface — see IDEA-40's ## Quyết định for the reasoning): this does NOT replace StorageKeys.maxMsSeen-based nowMsClamped(), and no existing service in this package has been migrated to call this instead. It's a standalone, fully-tested capability available for a service to adopt.

Constructors

TrustedClockService({Duration normalTolerance = const Duration(seconds: 5), Duration suspiciousJumpThreshold = const Duration(hours: 1), ClockSample sampleNow()?, TrustedTimeSource? trustedTimeSource})

Properties

hashCode → int
The hash code for this object.
no setterinherited
lastJudgement → ClockJudgement?
The most recent ClockJudgement nowMsTrusted computed — null before the first ever call (nothing to compare against yet). Exposed for a debug/QA panel to show live, not consumed internally.
no setter
normalTolerance → Duration
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
suspiciousJumpThreshold → Duration
final
trustedTimeSource → TrustedTimeSource?
Optional — see TrustedTimeSource.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
nowMsTrusted() → int
Trusted "now", in UTC epoch milliseconds. Never goes backward (rewind-proof, same guarantee nowMsClamped() gives), and never permanently locks onto a suspicious far-future jump (see class doc).
reconcileWithTrustedSource() → Future<void>
Lets a caller-supplied TrustedTimeSource confirm the CURRENT wall clock reading is legitimate, immediately re-anchoring the baseline to it even if the most recent nowMsTrusted call quarantined it as a ClockJudgement.suspiciousForwardJump. A no-op (never regresses the baseline) if the confirmed time is behind it, or if trustedTimeSource is unset or returns null.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited