Overview
Underneath widgets like Tyre Deg Table, Corrected Laps Plot and Timing Tower sits an insights layer: a set of metric calculations that watch the same live/replay data stream everything else does, and publish their own results back onto it. Every one of those results is versioned, so a chart never mixes numbers from two different generations of the same maths without you being able to tell.How It Works
Pure, Versioned Metrics
Each metric is a pure function of three things: the session state built up so far from the data stream, a set of event parameters (see below), and its own configuration. Feed it the same inputs twice and it produces the same output twice, whether that’s live, during a replay, or from a stored snapshot. Every metric output carries amodel_id (which metric produced it, for example corrected_laps or track_evolution) and a model_version. Published insight messages also carry confidence and inputs_through_lap, so a consumer always knows how far through the session the number is trustworthy.
The Version Rule
If the maths behind a metric changes, itsmodel_version must change with it. This isn’t just a convention: a golden-replay check runs a fixture session through the real engine and compares its output, metric by metric and version by version, against a committed golden file. A maths change without a version bump gets compared against the old version’s golden and fails the check. The fast per-commit gate runs this against a small synthetic fixture; the full gate before merging additionally samples one real weekend at random; a full sweep of every fixture is available for scheduled runs.
Some current model versions, for a sense of scale: fastest_lap is at 1.2.0, lap_classification at 1.3.0, running_order at 3.2.0 after several correctness fixes and a change of basis, corrected_laps at 1.4.0, track_evolution at 2.3.0, and stint_deg, compound_deg and race_pace are all at 1.9.0. The strategy metrics version differently again: their model_version is the composite of the engine build and the wrapper, currently 0.5.0-interim+b1.9.0. These numbers move as the maths is refined; check the insights service’s contract for the current values rather than treating any number here as permanent.
Live Computation vs Precompute
For a live session, the insights engine runs continuously, computing each metric as new laps and events arrive and publishing results the moment they’re ready. For an archived session, results are computed once, up front, by replaying the whole session through the same engine on a fast synthetic clock and persisting every output. Nothing is republished live; the rows simply exist. When you later open that session, whether live-replayed for demo purposes or simply queried, those precomputed rows are served back as if they were arriving on the insight channel, which is what lets you scrub anywhere in a stored session and see an insight update instantly rather than waiting for it to be recomputed.Parameters Are Data
Metrics that need circuit- or round-specific numbers, fuel sensitivity, tyre priors, pit-loss timings, read them from a versioned parameters store rather than having them hard-coded. Parameter rows are append-only: a correction writes a new version and flips which one is active, nothing is edited in place. Rows resolve with a fixed precedence, from general defaults up through circuit-specific, round-specific, to session-specific overrides.Explicit Degradation, Never a Guess
When a metric is missing a parameter it needs, it degrades explicitly rather than inventing a plausible-looking default. The fuel-corrected laps metric withholds its output entirely for a lap if fuel parameters for that round haven’t been loaded. The track evolution metric instead carries its own status field and, when it can’t do a full calculation, reports itself as degraded along with the reason, rather than silently drawing a curve it can’t stand behind.Where You See It in the App
You don’t seemodel_id or model_version directly in most widgets, but their effect is everywhere: a chart that looks slightly different after an update is on a new model version, not showing you a rendering bug. A widget that shows no data, or fewer laps than you expect, for part of a session is very likely reporting an explicit degradation (missing event parameters) rather than a fault.
FAQ
Why would a widget suddenly go blank partway through a session?
Why would a widget suddenly go blank partway through a session?
Most likely a required event parameter for that round hasn’t been loaded yet, or the metric doesn’t have enough laps to be confident. The metric is designed to withhold output in that case rather than show a misleading number.
If I see different numbers for the same session on two different days, what happened?
If I see different numbers for the same session on two different days, what happened?
The metric’s model_version probably changed. Since the maths is versioned and CI-checked, a change in output always corresponds to a real, deliberate change in the calculation, not drift.
Next Steps
Fuel Correction
A worked example of a versioned, parameter-fed insight.
Data Journey
Where the data that feeds these metrics comes from.
Tyre Deg Table
A widget built directly on versioned degradation metrics.
Corrected Laps Plot
See a fuel-corrected, versioned metric plotted directly.