compound_failure_advisor library

In-drive compound-failure caution advisor — the in-drive counterpart to pretrip_decision_advisor.

Where the pre-trip advisor answers "should I leave?" (and may honestly say wait), this answers the strictly different in-drive question — "conditions are degrading while I'm already moving on a snow road; how should I hold the wheel right now?" — and its ceiling is a gentle, reversible consider stopping, never turn back. The two share no decision surface and no verb.

It fuses position-trust × what-she-can-see (with advisory severity + speed as escalators) into one honest, immutable caution record. The one intentional non-linearity: position-uncertain AND low-visibility TOGETHER yields the strongest caution — the danger COMPOUNDS.

Pure Dart — zero runtime dependencies, no Flutter, no IO, no clock, no globals; 32-bit-ARM friendly; one total, deterministic, synchronous pure function (adviseInDrive). Advisory-only: it labels the moment; she drives it. See README.md.

Classes

DriveAdvice
One immutable, honest caution label on how to hold the wheel right now.
DriveAdviceMessages
The localized driver-facing strings for this package's advisory vocabulary. Resolve one for the active language; DriveAdviceMessages.en is the default and the fallback for any language this package does not (yet) carry.
DriveSituation
The in-drive situation, by value, at one instant.

Enums

AdvisoryLevel
Severity of the single most-severe in-area advisory the integrator has already selected.
CautionReason
Exactly which inputs raised the action — surfaced so the integrator can say WHY in the driver's own terms, with no re-derivation.
DriveAction
The entire actionable vocabulary — three rungs, a strict monotonic ladder.
PositionTrust
Trust in the current position estimate.
Unknown
First-class unknowns — the heart of the honesty contract, NOT a footnote.

Constants

kFastForConditionsMps → const double
Above this ground speed (~13.4 m/s ≈ 48 km/h) the driver is covering uncertain ground fast — an escalator when the core is already degraded.
kRadiusNeighbourhoodM → const double
A confidence radius beyond this (~150 m) means the dot is a neighbourhood, not a point — it bumps a degraded position to the worst tier.
kReactionTimeSeconds → const double
Reaction-time margin (s) folded into the sight-stopping-speed hint. Set to a winter, see-the-hazard-then-react figure (~2.5 s, well above the ~1.5 s used for alert dry-road braking) because spotting a stopped car in falling snow and beginning to brake takes longer. Caution-add-only.
kSightHintCeilingMps → const double
Hard ceiling (m/s) on the sight-stopping-speed hint. The hint is never surfaced above the "covering uncertain ground fast" threshold (kFastForConditionsMps, ~48 km/h): no matter how far she can see, the model itself treats anything faster as fast-for-conditions, so the hint must not suggest it. This bounds the sight-geometry result, which on its own ignores grip and could otherwise name an unsafe snow-road speed.
kStaleFixSeconds → const double
Seconds without a trusted fix beyond which a degraded position is "long blind" and bumps to the worst tier.
kVisClearM → const double
At/above this (~1 km) visibility is clear (concern 0).
kVisLowM → const double
At/above this (~200 m) visibility is low (concern 2); below it is the whiteout band (concern 3).
kVisReducedM → const double
At/above this (~500 m) visibility is reduced (concern 1).
kVisStaleSeconds → const double
A visibility reading older than this (~5 min) is too stale to trust and is treated as unknown. Snow squalls can collapse visibility from kilometres to metres inside this window, so this is a deliberately conservative ceiling on trust, not a promise the reading is still accurate — and it is a public const an integrator may shorten for fast-moving-squall regions.
kWinterDecelMps2 → const double
The deceleration (m/s²) the sight-stopping-speed hint assumes for the road surface. Calibrated to the WORST-CREDIBLE winter surface this package targets — glare / black ice (ブラックアイスバーン), μ ≈ 0.1, ~1.0 m/s² — NOT packed snow (~2.0). The hint must not assume a grip the worst morning cannot give: on the surfaces this package exists for, a higher figure would name a speed at which she could NOT actually stop. Caution-add-only: this may only ever be lowered. This is the one road-surface assumption the package makes; it is disclosed here and in the README honesty bounds, and it is a public const an integrator may lower further (never raise).

Functions

adviseInDrive(DriveSituation s) → DriveAdvice
Fuse position-trust × visibility (with advisory severity + speed as escalators) into one honest, immutable in-drive caution record.