Listening for events…
← All Docs

The Dex Data Model

Mike's mental model of how TerraPulse organizes its measured data, captured 2026-06-16. This is the top-level picture that docs/event-spine-framework.md (Eventdex) and docs/yeardex-framework.md (Yeardex) implement. It exists to keep one shared model so the structure isn't reconstructed from scratch each time.

The one idea

The dex is an indexed list of slots. Each slot holds exactly one thing: a single EVENT (Eventdex) or one YEAR's statistics (Yeardex). Walk the list and every stop is one or the other. Each phenomenon keeps its own list. These lists are organized measured data that papers draw from — data-prep in service of the paper mission, not a replacement for it, and never opposed to the analysis the papers do (see feedback_organize_not_process).

What a slot is

  • Event slot (Eventdex): one discrete event — a tornado, an eruption, a gravitational wave, a disaster declaration. Ordered on the time it occurred.
  • Year slot (Yeardex): one calendar year's statistics for a subject — US land use 1987, US dairy 2023. Keyed by the bare year.
  • Same phenomenon from several sources → one slot, each source cited. Folding several records of the same event/year into one slot (e.g. the NWS survey narrative onto an SPC tornado slot; the entry kind's four fireball catalogs) is organizing that one phenomenon, not duplicating it.
  • Each phenomenon is its own separate list/category. Neutrinos here, gravitational waves there, cosmic rays there. Phenomena stay separate as categories; you never dissolve one into another.

Storage: parallel lists, not one combined list (chosen for speed)

The slots live in per-phenomenon lists — physically, the storehouse keeps one directory of slot records per kind plus an index rebuilt from them. Events and years are kept parallel (the event_storehouse and the year_storehouse), not merged into a single list, because:

  1. Queries are scoped to one phenomenon at a time. Papers pull "all tornadoes in window T" or "land use by year," never events and years jumbled together. A smaller dedicated list means less to scan; a combined list makes every query wade past everything else.
  2. Events are live, years are frozen. Events tick in and backfill constantly; year statistics are settled history. Separate lists keep live writes from re-processing the static year data on every event tick.
  3. Different shapes read faster apart. An event carries time + place; a year carries a year + a stats table. Uniform lists avoid a per-element "event or year?" type check.

A combined list only wins the "give me literally everything at once" query, which papers do not run. If a whole-dex walk is ever wanted, stitch a combined view on top — cheap, and paid for only when used. (Parallel is also how it is already built, so this choice is zero rework.)

The linked-list requirement, already satisfied

Events do not arrive in chronological order: you backfill an old one, a live one lands today, a historical one gets discovered and must splice into its place on the timeline. Arbitrary middle-insertion is the classic reason to reach for a linked list over a fixed array. The current design meets that requirement without literal pointers: each slot is a separate record, and the time-ordered index is rebuilt from all of them on read, so a new slot drops into its correct place for free.

(If "linked" is later meant as cross-references between related slots — e.g. a gravitational-wave event pointing to the cosmic rays it was checked against — that is a by-reference link added per relationship, not the backbone of the list. It would be wired separately.)

Gravitational waves: one chirp per event (no special handling) — FINALIZED

Each detected chirp — one merger — is a single Eventdex event: one chirp, one slot, stamped with the merger time, exactly like every other kind (431 in the gw kind: GW150914, GW170817, …). Two compact objects spiral together and merge in under a second, and the detector records one rising "chirp"; it is not a group of waves, it is one swept signal from one collision.

It was briefly considered a "special case" because its location is a fuzzy sky region rather than an Earth point, and its value is a small parameter bundle (the two masses, distance, signal strength, spins, fit from the waveform) rather than one number. Those are just this kind's slot fields — every kind has its own (a tornado slot carries an EF rating and a track; a year slot carries a stats table). The slot's shape is not special and needs no special handling. Ruling (Mike 2026-06-16): "don't worry about the shape of the slot, we can neatly eventdex the chirps." Finalized — GW is an ordinary Eventdex kind.

(The cross-match of GW slots against other phenomena is a separate downstream read-across, not part of the event filing; it stays as-is.)

In service of the mission

Eventdex and Yeardex organize the measured data — measured reality only (feedback_measured_reality_only) — so the papers draw from it cleanly. Organizing feeds the paper mission; it does not replace it. Mike holds this mental model; when it is unclear how a phenomenon should be categorized, ask him rather than invent structure.

References

  • docs/event-spine-framework.md — the Eventdex implementation (event slots, per-kind storehouse).
  • docs/yeardex-framework.md — the Yeardex implementation (year slots).
  • Memory: feedback_organize_not_process, feedback_measured_reality_only, project_eventdex.
Live Feed