Ultra-High-Energy Cosmic Ray Eventdex — Scope + Frozen Settings
Status: rule FROZEN 2026-06-15 (Mike) · Owner: Mike + Claude (engine room)
Parent: docs/event-spine-framework.md (the Eventdex framework; this is kind #8 after tc, gst, eq, tor, vol, entry, and gw)
This document scopes the ultra-high-energy cosmic ray (UHECR) kind of the event storehouse: the most energetic individual particles ever measured hitting Earth's atmosphere. Each event is a single subatomic particle (a proton or atomic nucleus) arriving from space with macroscopic kinetic energy, tens of EeV (1 EeV = 10^18 eV; the 166 EeV record event carries the energy of a hard-thrown baseball in one particle), slamming into the upper atmosphere and triggering a cascade of secondary particles (an "air shower") that ground detector arrays record.
This is the second cosmic-messenger kind (after gravitational waves) and inherits GW's posture almost exactly:
- Cosmic origin, arrival direction not ground point. The particle's origin is extragalactic (for the highest energies) and what matters scientifically is the arrival direction on the sky (RA/Dec), not where the shower happened to land. Like GW, there is no meaningful terrestrial radius sweep.
- Catalog-first, catalog-only in practice. No ground sensor of ours correlates with an individual cosmic ray (they are random, isotropic-ish arrivals); a kilometre-scale air shower lights up no lightning network or seismometer. The value is the spine: a complete record of the most energetic particles ever caught, each with its energy and arrival direction. The real "sweep" is the directional multi-messenger cross-match (do UHECR arrival directions cluster with each other, or align with GW / neutrino events?), which is the same deferred v2 as GW's skymap sweep. v1 is catalog-only.
All counts below were verified 2026-06-15 against the live auger_uhecr source (131 rows, PG16).
The theme
The top of the cosmic-ray energy spectrum. Ordinary cosmic rays rain down constantly and are a flux, not events; but at the extreme high end the rate drops to roughly one particle per square kilometre per century, so each detection is a singular, nameable event. These are the particles near and above the GZK cutoff, the physics frontier of "how did nature accelerate a single proton to this energy." One kind, one timeline of the rarest, hardest-hitting particles in the measured record.
The spine (one source)
| Source | Population | Floor (FROZEN) | Slots | History | Status |
|---|---|---|---|---|---|
| Pierre Auger Observatory | UHECR air-shower events | full published Auger catalog | 109 | 2004+ | LIVE (auger_uhecr) |
131 catalog rows collapse to 109 distinct events. Auger records each event two ways: the
surface-detector reconstruction (uhecr_sd, 115 rows / 109 ids) and, when a fluorescence telescope
also caught the shower in the night sky, the higher-quality hybrid reconstruction (uhecr_hybrid,
16 rows / 10 ids). The 10 hybrid events are a subset of the 109; an event seen both ways is one
event, with the better reconstruction preferred (see collapse below). Energy span 46 -> 166 EeV,
2004-05-21 -> 2020-12-07. The smallest kind yet (gw is 431, gst 1,147). Pierre Auger is the
southern-hemisphere observatory in Malargüe, Argentina.
Slot ID — native event id, no prefix (FROZEN, with a noted caveat)
Following the single-source kinds (eq, vol, tor, gw use the native catalog id), the slot ID is the
Auger event id (the event_id field in extra_json), globally unique within the catalog.
Caveat (decided: bare for now). Unlike GWOSC, there is no unified UHECR catalog: the
northern-hemisphere Telescope Array publishes its own events separately. If TA is ever added,
UHECR becomes multi-source and the slot space must be source-prefixed (auger: / ta:), exactly
like the entry kind. For a single-source v1 the bare id is correct; the prefix migration is a small,
well-understood change gated on actually adding TA.
Collapse — prefer hybrid (FROZEN)
For each event id, collapse the SD and hybrid rows to one canonical record, preferring the hybrid reconstruction when present (SD + fluorescence gives a better energy and direction than SD alone), keeping the SD values as provenance. This is the direct analogue of GW's version-collapse (prefer the most authoritative reconstruction; keep the rest as history).
The floor / population — FROZEN
Full published Auger catalog, no further floor (mirroring CNEOS bolides: every entry is already a vetted high-energy event). Auger's public event releases are already the high-energy selection (this dataset floors at 46 EeV); there is no sub-threshold tier to flag, unlike GW's marginal candidates. All 109 distinct events are slots.
The sweep — catalog-only v1 (FROZEN), directional multi-messenger is v2
Identical posture to GW, for the same physics:
- Geometry: none. No ground point, no radius. The scientific position is the arrival direction (RA/Dec), an extragalactic line of sight, irrelevant to Earth-fixed sensors.
- v1: catalog-only. No terrestrial sensor sweep is fired. Each slot accretes the full air-shower reconstruction (energy, direction, detector, shower shape). An individual cosmic ray correlates with nothing our ground/space layers record, so a temporal/spatial sensor sweep would be pure noise, the same flood lesson GW's Brick C taught.
- v2 (deferred, shared with GW): the directional cosmic-messenger cross-match. The real multi-messenger question is whether UHECR arrival directions cluster with each other (anisotropy / point sources) or align in time+direction with GW or neutrino events. That needs the same sky-direction-match machinery GW's v2 skymap sweep needs, built once for the whole cosmic-messenger cluster (gw + uhecr + neutrinos). Out of scope for this freeze.
Honest expectation (FROZEN): every UHECR slot is catalog-only. The product is the catalog of the most energetic particles ever measured. This is expected and fine, the spine is the product.
Measured-reality rule (FROZEN)
An air shower is a measured cascade (the detector array records real particle hits). The primary particle's energy and arrival direction are reconstructed from that measurement, by the same inference class we already ship: an earthquake magnitude from seismic waves, a bolide's kilotons from its light curve, a GW's masses from its strain. Per the bright line ([[feedback_measured_reality_only]]):
- IN: the detection (arrival time, detector), and the reconstructed energy, arrival direction (RA/Dec, zenith/azimuth), and shower parameters (risetime, multiplicity) as published by Auger.
- OUT: simulated/predicted showers, flux models, any inferred source catalog that is a model rather than a measured arrival. None of these are in the Auger event release.
Dossier shape
Common header (event_id, when = arrival time, kind_subtype = detection mode sd / hybrid).
Source-native extras: energy_eev + energy_uncertainty_eev, arrival direction ra_deg / dec_deg
and zenith_deg / azimuth_deg, risetime_ns, multiplicity, detector reconstruction provenance.
No ground point (cosmic-origin); the empty sensor section follows the GW catalog-only pattern. Kind
directory: data/event_storehouse/uhecr/. Kind code uhecr.
Data-source notes / gotchas (recorded for the build bricks)
- The spine is already live.
auger_uhecrholds the full catalog; Brick B is a collapse + verify (109 events, hybrid-preferred), not a reload, exactly like GW Brick B. - Live edge is dormant. Auger publishes events in batched public data releases years after the fact (the current set ends 2020-12). The fetcher's newcomer-skip keeps it idempotent; genuinely new events arrive only with the next Auger release. Same dormant-but-uniform posture as meteorite falls.
- Reuse GW's machinery. uhecr is the catalog-only twin of gw: the same no-radius config shape,
the same "collect the full reconstruction into the slot, defer the directional sweep" build. The
gw_sweepmodule is the template; the cosmic-messenger directional sweep, when built, serves both.
Build bricks
- Brick A — freeze. THIS DOC (2026-06-15, Mike): theme, single Auger spine, full-catalog floor, native-id slot (bare, with the TA multi-source prefix caveat), SD/hybrid collapse (hybrid-preferred), catalog-only v1 sweep with the directional multi-messenger cross-match deferred to the shared cosmic-messenger v2, and the measured-reality rule placing reconstructed energy/direction IN by the eq/bolide/GW precedent.
- Brick B — spine collapse + verify. DONE 2026-06-15:
scripts/build_uhecr_spine.pycollapsed the 131 reconstruction rows to 109 distinct events (hybrid-preferred; 10 events carry both SD + hybrid, 99 SD-only), confirmed energy span 51.5 -> 166 EeV (the collapsed canonical min is 51.5; the 46 in the raw rows was a superseded duplicate) and the 166 EeV headline (2019-11-10, RA 128.9 Dec -52.0). Span 2004-05-21 -> 2020-12-08. Audit roster written todata/uhecr_spine_roster.parquet(in data/, NOT the uhecr/ dossier dir). - Brick C — kind registration, catalog-only. DONE 2026-06-15:
src/terrapulse/monitor/ uhecr_sweep.pyregisters theuhecrkind (UHECR_CONFIG: radius_km=None, sensor_slugs=(), the SD/hybrid collapse logic), scheduler job (uhecr_sweepevery 1800 s) + missing-slot newcomer probe. Catalog-only from the start — no sensor sweep is built or fired (the GW flood lesson applied up front);build_dossierrecords the full Auger reconstruction and marksmulti_messenger="deferred-v2-directional". 4 unit tests; full suite 212. - Brick D — dossier backfill. DONE 2026-06-15:
uhecr_sweep.backfill_and_store()built 109 dossiers (99 sd + 10 hybrid, 0 sensor hits by the catalog-only design). 1-slot-per-event verified (109 files == 109 unique event_ids). Marquee card = the 166 EeV cosmic ray of 2019-11-10. Eight-kind storehouse census: 139,314 (uhecr 109 + gw 431 + entry 25,520 + tor 73,634 + eq 13,840 + tc 13,544 + vol 11,089 + gst 1,147). The UHECR kind is COMPLETE (A+B+C+D). - First report: deferred. Engine room, not paper mode.