Skip to content

Rely solely on lead-time tiering for confidence - #7

Merged
chriselsen merged 3 commits into
mainfrom
refactor/lead-time-tiering-only
Aug 24, 2026
Merged

chriselsen merged 3 commits into
mainfrom
refactor/lead-time-tiering-only

Conversation

@chriselsen

Copy link
Copy Markdown
Contributor

Summary

Surfaces forecast confidence tiering in metadata and removes the multi-issuance
confirmation mechanism, leaving lead-time tiering as the single confidence
signal.

Added

  • leadTimeDays and leadTimeTier (Warning 0-2d / Watch 3-5d / Outlook 6+d)
    in metadata on both gauge point and basin polygon features, and in
    OutputSchema — so they're usable in CloudTAK filter expressions and
    highlight templates
  • A Confidence: Watch (+4d lead time) line in remarks for the headline
    severity, plus a tier tag in the gauge callsign, e.g.
    Flood Gauge — EXTREME (RISE) [Watch]

Removed (breaking)

  • MIN_CONFIRMING_ISSUANCES and INCLUDE_PRELIMINARY_EVENTS environment
    variables
  • confirmed and preliminary fields from metadata and OutputSchema
  • The (preliminary) callsign/remarks labels and reduced polygon fill opacity
  • buildConfirmedForecasts(), isSeverityConfirmed(), and the
    ConfirmedForecastRange type (replaced by the simpler
    TieredForecastRange)

Why

Lead-time tiering is grounded directly in Google's published model-skill data,
which measures the exact phenomenon behind false urgency at long lead times.
The confirmation check was a proxy for the same thing: it cost a second env var,
two methods, and retention of every forecast issuance in a 7-day window, while
having the least history to check against at exactly the short lead times
where alerts matter most — the opposite of where extra scrutiny is useful.

As a side effect, fetchForecasts() now returns only the latest issuance per
gauge instead of all issuances in the window, reducing per-run memory use.

Upgrade notes

Anything reading metadata.confirmed / metadata.preliminary, or filtering on
them in CloudTAK, needs to move to metadata.leadTimeTier /
metadata.leadTimeDays. Both removed env vars can simply be dropped from layer
config; they're no longer read.

Note there is no longer any way to suppress low-confidence alerts — everything
elevated is emitted, labeled with its tier. If that filtering is wanted later,
the cleaner form would be a MIN_CONFIDENCE_TIER var keyed off tiering rather
than reintroducing issuance history.

Testing

  • npx tsc --noEmit — passes
  • npm run lint — passes
  • npm run build — passes
  • npm audit — 0 vulnerabilities
  • grep confirms no leftover references to the removed symbols/vars

Not verified: end-to-end run against the live Google Flood Forecasting API
(requires API_KEY/ETL_* credentials), so the tier values on real gauge data
haven't been observed directly.

Expose forecast confidence tiering in metadata and remove the
multi-issuance confirmation mechanism.

Added:
- leadTimeDays and leadTimeTier (Warning/Watch/Outlook) in metadata on
  both gauge point and basin polygon features, plus in OutputSchema so
  they are usable in CloudTAK filters and highlight templates
- Confidence line in remarks showing the headline severity's tier and
  lead time, and a tier tag in the gauge callsign

Removed:
- MIN_CONFIRMING_ISSUANCES and INCLUDE_PRELIMINARY_EVENTS env vars
- buildConfirmedForecasts() and isSeverityConfirmed()
- confirmed/preliminary metadata and schema fields, the (preliminary)
  callsign/remarks labels, and reduced polygon opacity
- ConfirmedForecastRange, replaced by the simpler TieredForecastRange

Lead-time tiering is grounded directly in Google's published
model-skill data, which is the phenomenon that causes false urgency at
long lead times. The confirmation check was a proxy for the same thing:
it added a second env var, two methods, and retention of every issuance
in a 7-day window, while having the least history to check against at
exactly the short lead times where alerts matter most.

fetchForecasts() now returns only the latest issuance per gauge instead
of all issuances in the window, reducing per-run memory use.
@chriselsen
chriselsen merged commit 85c615a into main Aug 24, 2026
1 check passed
@chriselsen
chriselsen deleted the refactor/lead-time-tiering-only branch August 24, 2026 04:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant