Gravitational-Wave 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 #7 after tc, gst, eq, tor, vol, and entry)

This document scopes the gravitational-wave kind of the event storehouse: every gravitational wave that LIGO/Virgo/KAGRA has detected, each a black-hole or neutron-star merger that happened hundreds of millions to billions of light-years away and rang Earth's detectors for a fraction of a second. It is the first cosmic-origin kind (the source is extragalactic, not terrestrial), the smallest kind by count, and the most catalog-first, sweep-lightest kind yet — more so than even atmospheric entry.

Three properties make it different from every prior kind:

1. The source is not on Earth. There is no ground point, no radius, no geographic sweep. A merger's "location" is a sky region tens to thousands of square degrees wide, hundreds of Mpc away. The sweep, where it exists at all, is a temporal multi-messenger coincidence against our photon layers, not a 100 km circle.
2. The catalog is the entire product. The sweep will be empty for essentially every historical event (see The sweep). The value is the spine: a complete browsable wall of every detected merger, each with its measured physical parameters (component masses, distance, spins, signal strength). Multi-messenger is a forward-looking hook, not a populated column.
3. Version multiplicity IS the spine-upgrade mechanism. Each event is re-published across successive catalog releases (GWTC-1 -> 2 -> 2.1 -> 3 -> 4.0/4.1 -> 5.0, plus independent IAS analyses). The slot collapses those versions to one record, populated by the latest authoritative release. This is the cleanest realization yet of "the live edge fills the entry the historical record later refines."

All counts below were verified 2026-06-15 against the live gwosc_events source (6,870 rows, PG16).

The theme

Every confirmed ripple in spacetime that a ground detector has caught. Binary black hole mergers (the bulk), binary neutron star mergers (rare, the multi-messenger jackpots), and the in-between neutron-star-black-hole mergers. One kind, one timeline, from the first detection GW150914 (2015-09-14, the discovery that won the 2017 Nobel) through the ongoing O4 run.

The spine (one source)

Source	Population	Floor (proposed)	Slots	History	Status
GWOSC event catalog	LIGO/Virgo/KAGRA detections	all catalogued events, tier-flagged	431	2015+	LIVE (gwosc_events)

433 distinct catalog names, of which 431 are astrophysical events after Brick B screens 2 non-detection entries (a 2005 GRB targeted search + a 2010 blind injection); 410 GW-named confident detections + 21 marginal sub-threshold candidates, drawn from 6,870 catalog-version rows. The smallest kind yet (gst is 1,147), and it grows as O4/O5 events are published. Endpoint: https://gwosc.org/eventapi/jsonfull/allevents/ (no auth), already polled by the live fetcher.

Slot ID — native, no prefix (single-source convention)

Following the single-source kinds (eq uses the ComCat id, vol the eruption number, tor the SPC id), the slot ID is the GWOSC common name, which is already globally unique and self-namespacing:

• GW150914, GW170817, GW190521, ... for confident detections.
• 151008, 151012.2, ... (bare YYMMDD) for marginal candidates that never earned a GW designation.

Kind directory: data/event_storehouse/gw/. Kind code gw.

Version collapse (FROZEN)

For each event_name, the catalog holds one row per release it appeared in (GW170817 alone has 36). The slot is populated by the most authoritative / latest catalog version, with earlier versions and independent (IAS) analyses retained in the dossier's catalog_history block. Precedence (highest wins): GWTC-5.0 / 4.1 / 4.0 (the main LVK catalogs) > -confident releases > discovery papers > -marginal / preliminary / IAS. The newest LVK confident parameter estimate is the headline; everything else is provenance.

The floor / population — DECIDED 2026-06-15 (Mike, FROZEN)

Include every catalogued event, flag the tiers, drop nothing (mirroring how the SATCAT and GMN floors were set). Per the platform's measured-reality principle ([[feedback_measured_reality_only]] and [[feedback_no_spiking_global]]), a marginal candidate is still a real strain-data trigger — a measurement below the confidence threshold, not a fabrication. Like GMN's photometry_reliable flag and SATCAT's earth_reentry flag, we keep it and mark it:

• confidence_tier = "confident" — the 410 GW-named events (in a main GWTC release or a -confident catalog, FAR below the confident threshold). The real detections.
• confidence_tier = "marginal" — the 23 bare-YYMMDD sub-threshold candidates (-marginal / IAS / preliminary catalogs only, never promoted to a GW name).

Considered and not taken: a confident-only hard floor (410 events, dropping the 23 marginals), analogous to the SATCAT R/B+PAY floor. Rejected in favor of include-all-flagged — don't drop real measured triggers; the tier flag preserves the distinction without discarding data.

The sweep (per-kind settings, FROZEN)

This is the kind where the sweep model breaks from every predecessor, by physics:

• Geometry: none. No ground point, no radius. The source is extragalactic; the sky localization is tens to thousands of square degrees and irrelevant to Earth-fixed sensors.
• Sweep type: temporal multi-messenger coincidence. For a merger at GPS time t, check whether any photon/transient layer recorded a candidate counterpart in the follow-up window.
• Layer: fink_transients (optical transients — the kilonova / afterglow channel, the GW170817 story). This is the only layer we hold that could plausibly carry a real GW counterpart. We do not have a gamma-ray-burst feed (Fermi GBM / Swift BAT); GOES GLM is optical lightning, not prompt gamma, so it is not a counterpart layer here (a deliberate exclusion, noted so a future brick does not wrongly wire it in).
• Window: [t - 1 h, t + 14 d]. A binary-neutron-star counterpart is a kilonova that brightens over hours to days and an optical afterglow over days to weeks (GW170817's kilonova peaked ~1-2 days post-merger); there is no pre-merger optical precursor, so the window is forward-heavy.
• Sky-position refinement: v1 is a pure time coincidence (flag any fink transient in the window). A later enhancement could intersect the transient's RA/Dec with the GW skymap; deferred (the allevents API gives a sky-area number, not the full healpix map, so a real skymap cross-match needs a second fetch — out of scope for the freeze).

Honest expectation (FROZEN, do not re-litigate at Brick D): the sweep is empty for essentially every historical event. fink_transients coverage begins 2026-02-09; the catalogued GW events run 2015 -> 2025-02. Zero temporal overlap. No historical merger can produce a fink coincidence, by construction. The sweep earns a hit only for a future O4/O5 event published while fink is live and accompanied by a real optical counterpart — i.e. a second GW170817, which is a once-a-decade event. This kind is therefore catalog-only in practice: 431 full dossiers, each accreting the full LVK parameter estimate, with the multi-messenger sweep deferred. The spine is the product.

v1 catalog-only, decided 2026-06-15 (Brick C verification). The temporal-only sweep was built and tested, and the test exposed that an all-sky 14-day coincidence floods: a synthetic event in fink's coverage returned the 5,000-row cap, flagging every transient in the window with no way to separate a real kilonova from unrelated ZTF alerts. A meaningful counterpart search needs the GW localization skymap (sky-position cross-match) and applies only to BNS/NSBH events (a binary black hole produces no light). So v1 ships catalog-only: build_dossier records the parameters and marks multi_messenger="deferred-v2-skymap" plus counterpart_candidate (the 12 BNS/NSBH), and does not fire the flooding temporal sweep. The skymap-based sweep (a second GWOSC fetch) is the documented v2; sweep_event is kept and tested as its basis.

Measured-reality rule — GW parameters (FROZEN)

A gravitational-wave detection is a measured strain transient — a real distortion of spacetime that physically passed through the detectors. The component masses, luminosity distance, spins, and redshift are inferred from that measured signal by Bayesian matched-filtering against general-relativity waveform templates. This is IN, by direct precedent with kinds we already ship:

• An earthquake magnitude is inferred from recorded seismic waves via an Earth model — we ship it (eq).
• A bolide's kiloton impact energy is inferred from its radiated light curve — we ship it (entry/CNEOS).
• A hurricane's intensity is inferred from measurements — we ship it (tc).

GW parameters are the same class: physically-inferred properties of an event that actually happened, derived from a real measurement. That is categorically different from a forecast of what will or might happen. The bright line ([[feedback_measured_reality_only]]):

• IN: the detection (GPS time, network SNR, FAR, p_astro), and the inferred source parameters (component masses, chirp/total/final mass, luminosity distance, redshift, effective spin) as published in the LVK catalog.
• OUT: predicted/simulated mergers (population-synthesis events that were never detected), forecast detection rates, "expected" future events. None of these appear in the GWOSC event catalog, so the source is clean as-is.

Dossier shape

Common header (event_id = common name, when = GPS->UTC merger time at sub-second precision, confidence_tier, kind_subtype = BBH / BNS / NSBH inferred from component masses). Source-native extras: component masses mass_1_source / mass_2_source, chirp_mass, total_mass, final_mass, luminosity_distance_mpc, redshift, chi_eff, network_snr, far, p_astro, catalog (latest) + catalog_history (all versions/analyses), gps_time, GWOSC jsonurl + discovery reference. The (almost always empty) per-sensor section follows the eq/tor/vol/entry pattern. No geographic point (extragalactic source); sky-area, if captured at Brick B, is metadata, not a map coordinate.

Data-source notes / gotchas (recorded for the build bricks)

• The spine is already largely ingested. gwosc_events is live with 6,870 rows / 433 distinct events. Brick B is mostly a collapse + verify, not a fresh multi-GB reload like entry's four spines. The fetcher already pulls the full-parameter jsonfull endpoint.
• Two name formats. GW-prefixed = confident; bare YYMMDD (e.g. 151008) = marginal candidate. The confident/marginal tier is derived from the name format and the set of catalogs the event appears in (a name only ever in -marginal/IAS/preliminary sets is marginal).
• Screen test/injection entries at Brick B. The live copy carries an event dated 2005-11-03, which predates the first real detection GW150914 (2015-09-14). Early Initial_LIGO_Virgo / O1_O2-Preliminary rows may include blind hardware injections or mock-data-challenge entries. Brick B must verify the 433-event roster against the real LVK detection list and flag/exclude any non-astrophysical test entries (do not silently keep a 2005 "merger").
• psycopg2 + LIKE 'GW%' gotcha (recorded so the analysis scripts don't trip it): the % in a LIKE literal collides with pyformat parameter substitution and throws IndexError: tuple index out of range. Pass the pattern as a bound parameter (LIKE %s, 'GW%') or escape as %%.
• GPS->UTC is already handled in the fetcher (GPS epoch 1980-01-06, 18 leap seconds). Sub-second merger times are real (the signal is localized to milliseconds), so every event is timestamp- precise — but with no ground point, precision buys nothing for a geographic sweep; it only matters for the temporal multi-messenger window.

Build bricks

• Brick A — freeze. DONE 2026-06-15 (Mike): theme, single GWOSC spine, the include-all-flagged population (433 events, confident-only considered and rejected), native-name slot ID, version-collapse rule, the no-geometry temporal multi-messenger sweep against fink_transients (with the honest zero-historical-overlap expectation), and the measured-reality rule placing GW source parameters IN by the eq/bolide/hurricane precedent.
• Brick B — spine collapse + verify. DONE 2026-06-15: scripts/build_gw_spine.py collapsed the 6,870 catalog-version rows to one canonical record per event_name (highest CATALOG_RANK wins; all releases kept in catalog_history), classified confidence_tier + kind_subtype, and screened the non-astrophysical entries the freeze flagged. 433 catalog names -> 2 screened (GRB051103, the 2005 Initial-LIGO GRB targeted search; blind_injection, the 2010 "Big Dog" blind injection) -> 431 astrophysical slots. Span now starts exactly at GW150914 (2015-09-14 09:50:44) -> GW250207 (2025-02-07), the ghost 2005 row gone. 410 confident + 21 marginal; subtypes 283 BBH / 10 NSBH / 2 BNS (GW170817 + GW190425, the only two known) / 136 unknown (marginal candidates + events without published masses). GW170817 verified: BNS, 40 Mpc, 1.46/1.27 Msun (textbook). Loudest = GW250114 (network SNR 78.6, O4). Audit roster written to data/gw_spine_roster.parquet (in data/, NOT the gw/ dossier dir — the storehouse index globs *.json there). The fetcher is unchanged: raw all-version rows stay in observations; the collapse/tier/screen is storehouse-layer logic Brick C ports into the gw spine query (same pattern as entry). Kind slot count is therefore 431, not the freeze's 433 estimate.
• Brick C — kind registration + sweep, v1 catalog-only. DONE 2026-06-15: src/terrapulse/monitor/gw_sweep.py registers the first cosmic-origin kind — GW_CONFIG (radius_km=None, window [-1 h, +14 d], layer fink_transients), the roster collapse/tier/subtype logic Brick B verified, a scheduler job (gw_sweep every 1800 s) and a missing-slot newcomer probe. Sweep finding (verification caught it before ship): the temporal-only sweep_event works — a synthetic event placed inside fink's coverage returned the 5,000-row cap — but that is exactly the problem: an all-sky 14-day temporal coincidence flags every optical transient fink saw in the window (thousands), unable to tell a real kilonova from unrelated ZTF alerts. A meaningful counterpart search needs the GW localization skymap (sky-position cross-match) and applies only to BNS/NSBH (a binary black hole radiates no light). Decision (Mike, "we basically just collect info built into each slot"): ship v1 CATALOG-ONLY. Each slot accretes the full LVK parameter estimate; build_dossier does NOT fire the flooding sweep (swept=False, multi_messenger="deferred-v2-skymap", counterpart_candidate flags the 12 BNS/NSBH). This is also literally the real state today — the catalog ends 2025-02 and fink starts 2026-02, so every event has zero counterpart hits regardless. sweep_event/_TEMPORAL_HITS_QUERY are kept + tested as the v2 basis (skymap match, BNS/NSBH-gated, second GWOSC fetch). 7 unit tests; full suite 208.
• Brick D — dossier backfill. DONE 2026-06-15: gw_sweep.backfill_and_store() built 431 dossiers in ~11 s (one slot per astrophysical event), all catalog-only (0 sensor hits, by the v1 decision). 410 confident + 21 marginal; 283 BBH / 10 NSBH / 2 BNS / 136 unknown; 12 BNS/NSBH counterpart-candidates flagged. 1-slot-per-event verified (431 files == 431 unique event_ids). Marquee cards correct: GW170817 (BNS, 1.5+1.3 Msun, 40 Mpc), GW190425 (BNS, 2.1+1.3 Msun, 150 Mpc), GW150914 (BBH, 35+30 Msun, 470 Mpc). Seven-kind storehouse census: 139,205 (gw 431 + entry 25,520 + tor 73,634 + eq 13,840 + tc 13,544 + vol 11,089 + gst 1,147). The gravitational-wave kind is COMPLETE (A+B+C+D).
• First report: deferred. Engine room, not paper mode.