condition_aggregator 0.0.2

Source-neutral interface for severity-qualified meteorological-advisory aggregation. Defines Advisory typed event + AdvisoryProvider interface consumed by per-source adapter packages (NWS / JMA / etc. [...]

Changelog

0.0.2 — 2026-05-04 — Advisory staleness model

Adds publisher-effective-time-derived freshness to the typed advisory event, so integrators can render freshness honestly rather than treating a last-fetched-an-hour-ago snapshot as "current."

Driver-facing rationale: "advisory carries its own freshness; the driver knows when the source last updated." When a publisher (NWS / JMA / ...) has updated an advisory and a stale snapshot is still in flight, the integrator composes Advisory.stalenessAt(now) with a per-event-class staleness budget to surface freshness honestly.

Added

• Advisory.stalenessAt(DateTime now) returning Duration?:
  • null when the publisher did not declare an effective timestamp (unknown-freshness; semantically distinct from known-fresh and known-stale at this layer).
  • Duration.zero clamping for advisories whose effective is in the future relative to the consumer's clock — the advisory was published for the future and is fresh by definition; we do not let a clock-skew artefact present as "negative staleness."
  • Otherwise now − effective.
• Advisory.isStaleAt(DateTime now, Duration threshold): true iff effective is non-null AND stalenessAt(now) >= threshold. False on unknown-freshness (publisher omitted effective); the package does not assert staleness on unknown ground.

Tests

• 7 new tests covering: null-effective returns null staleness; past-effective produces correct delta; future-effective clamps to zero; isStaleAt false on unknown-freshness; isStaleAt true on delta-meets-threshold; isStaleAt false on delta-below-threshold.

Unchanged (back-compat)

• All 0.0.1 surface unchanged. effective / expires / isHighImpact / isExpiredAt semantics identical.
• AdvisoryAggregator / AdvisoryProvider / AdvisoryAggregateResult / AdvisoryProviderError / AdvisoryProviderInitException unchanged.

0.0.1 — 2026-05-03

Initial publish.

• Advisory typed event normalized across publisher sources (severity / certainty / urgency / area / effective / expires).
• AdvisorySource enum (nwsUnitedStates, jmaJapan, other).
• CAP-class enums: AdvisorySeverity, AdvisoryCertainty, AdvisoryUrgency.
• AdvisoryProvider adapter contract with mandatory init() lifecycle and fetchActiveAdvisoriesAtPoint(lat, lon) method.
• AdvisoryAggregator multi-source fan-out primitive with warn-and-continue per-provider failure capture.
• AdvisoryProviderInitException, AdvisoryAggregateResult, AdvisoryProviderError supporting types.
• 11 tests covering the value-object, init lifecycle, fan-out merge, warn-and-continue per-provider error capture, init-failure propagation, init idempotency.
• BSD-3-Clause license (matches the rest of SNGNav).
• Pure Dart, no Flutter dependency.