Status: Foundation design and staged implementation
Last reviewed: August 31, 2026
Companion page: RaceIQ Machine Learning Runtime, Distribution, Training, and Personalization

This page explains how RaceIQ's telemetry, deterministic analysis, AI, live-engineer, and future machine-learning systems are intended to fit together. It is an architectural overview, not a replacement for the detailed acceptance criteria in each issue.

RaceIQ's machine-learning foundation is not one model or one training pipeline. It is the complete evidence system required to turn simulator-specific telemetry into data that can be understood, trusted, compared, rebuilt, and eventually used for model training.

The foundation is intended to answer questions such as:

• What exactly happened during a session?
• Which participant, stint, lap, corner, and telemetry range did it affect?
• Was the source data complete and sufficiently detailed?
• Is the evidence suitable for this particular calculation?
• Which parser, schema, detector, policy, and configuration produced the result?
• Can the result be reproduced from the original recording or canonical archive?
• Can an AI or machine-learning system use the result without guessing what missing or low-quality data means?

This foundation supports three related but separate product areas:

1. Deterministic RaceIQ analysis, such as lap comparison, corner measurements, fuel calculations, stint analysis, and evidence-backed findings.
2. AI explanation, where an AI model explains or prioritizes trusted findings instead of inventing conclusions directly from an uncontrolled telemetry dump.
3. Future machine learning, where training examples can be selected using explicit quality, classification, provenance, and eligibility rules.

RaceIQ is therefore building the trusted evidence layer before treating accumulated telemetry as training data.

Raw telemetry is not automatically good training data.

A lap may be structurally valid but still be inappropriate for normal pace analysis because it was:

• an out lap;
• an in lap;
• a grid-start lap;
• completed under caution;
• interrupted by pit-lane travel;
• affected by an incident;
• recorded with a major telemetry gap.

The same lap may still be suitable for another purpose. A caution lap may contain valid fuel-use evidence. A lap with missing tire temperatures may still have perfectly usable speed, brake, throttle, steering, position, and lap-time data. A brief gap on a straight may not matter for lap timing but could make a short wheel-slip event impossible to evaluate.

RaceIQ therefore must not use one generic isValid flag for every analysis. It needs to preserve the evidence and separately record:

• what kind of lap or range it was;
• how trustworthy the recording was;
• how each telemetry channel was supplied;
• what analyses that evidence can support;
• why an analysis was allowed, limited, rejected, or left unknown.

Without those distinctions, a machine-learning model could learn caution behavior as normal pace, interpret an unavailable channel as zero, combine incompatible stints, or train on imported and native data as though they had equal fidelity.

Simulator, import, or external telemetry source
 ↓
 Versioned source evidence
 (#130 and related work)
 ↓
 Canonical semantic telemetry
 (#205)
 │
 ┌────────────┴────────────┐
 │ │
Live in-memory processing .bin / .bin.gz recorder
and analysis state only live persistence writer
 │ │
 │ ↓ after session
 │ Replay through canonical pipeline
 │ ↓
 │ Canonical Parquet archive
 │ (#232)
 │
 ├── Lap classification (#229)
 ├── Race-event timeline (#234)
 ├── Quality and eligibility (#236)
 ├── Stints and pace segments (#235)
 ├── Laps, corners, and segments (#232)
 └── Deterministic findings (#237)
 ↓
 UI / reports / Setup Engineer / AI
 ↓
 Live-engineer decision ledger (#238)

Two systems apply across the entire pipeline:

#233 — records provenance, versions, generations,
 rebuild state, and verification
#239 — proves that live processing, raw replay,
 archive conversion, and archive rebuild
 produce the same semantic racing facts

This is not meant to be one giant service or detector. Each domain owns a focused contract, but every domain shares stable identities, canonical telemetry semantics, quality rules, provenance, and deterministic processing boundaries.

RaceIQ should preserve the distinction between the following layers.

Changing the wording of a message must not change the identity of the underlying fact or finding. Likewise, changing an AI model must not silently change what RaceIQ believes happened in the session.

These issues are not part of the numbered #229/#232–#239 group, but the ML foundation depends on them.

This provides the source, session, participant, connection, sequence, timestamp, race-control, and source-frame architecture.

It matters because later analysis must not assume:

• every source is UDP;
• every session contains only one vehicle;
• a participant and driver are the same identity;
• wall-clock time is the authoritative timeline;
• every simulator exposes the same capabilities;
• reconnects and source resets can be ignored.

This defines the canonical meaning of telemetry values across games.

For every semantic telemetry value, the catalog should identify:

• stable semantic ID;
• canonical unit and value type;
• native source field;
• mapping status;
• source fidelity;
• freshness behavior;
• derivation requirements;
• lost detail or simulator limitations.

A single tire-temperature value must remain distinguishable from inner, middle, and outer temperatures. A derived opponent speed must remain distinguishable from directly measured player speed.

The catalog tells RaceIQ what a value means. The quality system then determines whether the available evidence is suitable for a particular use.

The following are not the core ML architecture, but they support trustworthy testing and future datasets:

• #217 — Raw-recording retention and cleanup
• #240 — Garage 61 API integration
• #241 — Long-form golden recordings
• #242 — Golden recording manifests

Issues #229 and #232–#237 form the main evidence and deterministic-analysis foundation.

Issue #238 is primarily the safe live-deployment layer. It becomes relevant when findings or future models begin proposing real-time advice.

Issue #239 is the verification and release gate. It should grow incrementally as each domain lands rather than being postponed until the very end.

The practical dependency direction is:

#236 quality foundation
 ↓
#234 race-event timeline
 ↓
#235 session runs and pace segments
 ↓
#233 provenance receipts and generations
 ↓
#232 canonical archive and hierarchy
 ↓
#237 deterministic findings
 ↓
#238 live-engineer decisions
 ↓
#239 complete cross-path parity

This is not a perfect one-way dependency graph. For example, #229 classification is required by quality and also becomes more accurate when it can use events from #234. The important rule is that each layer should consume stable contracts from lower layers instead of independently reinventing the same fact.

Lap validity and lap classification are different concepts.

A lap may be structurally valid and worth retaining while still being unsuitable for normal pace comparison.

Initial classifications should support concepts such as:

normal flying lap
out lap
in lap
pit lap
grid-start lap
caution lap
formation or slow-zone lap
partial lap

The classification should be available to:

• Analyse and Compare;
• stint and pace calculations;
• driver profiles;
• race reports;
• findings;
• AI context;
• live callout rules;
• future ML dataset selection.

Classification should not delete the telemetry. It should describe the context so each analysis can decide whether that lap is eligible.

A caution lap, for example, might be:

Structurally valid: yes
Normal pace: excluded
Fuel-use evidence: possibly eligible
Race-control analysis: eligible
Stored and viewable: yes

RaceIQ should keep .bin or .bin.gz as the only persistent writer during a live session.

During the session:
Simulator
 ↓
Canonical telemetry
 ├── Live in-memory analysis
 └── Existing raw recorder

RaceIQ should not continuously write a second Parquet copy beside the raw recorder. Live analysis should use the canonical stream and bounded in-memory state.

After the session:

Raw .bin / .bin.gz recording
 ↓
Replay through parser and canonical resolver
 ↓
Verified canonical Parquet archive
 ↓
Historical Analyse / Compare / rebuild / future ML

The canonical archive should contain telemetry once. Higher-level records should point to time, row, tick, and track-distance ranges instead of copying telemetry into every object.

Conceptually:

Session
├── Shared session evidence
│ ├── Weather
│ ├── Race control
│ └── Track state
│
└── Participant / vehicle
 ├── Participant runs
 ├── Tire stints
 ├── Driver stints
 └── Pace segments
 └── Laps
 └── Corners
 └── Semantic segments
 ├── Braking
 ├── Turn-in
 ├── Entry
 ├── Apex / minimum-speed region
 ├── Exit
 └── Throttle pickup

Entry, mid, and exit are useful initial segment types, but the architecture must not permanently limit corners to three equal pieces. Boundaries should be based on track position and telemetry behavior where possible.

The hierarchy is an index and domain model, not another telemetry-storage format.

The same hierarchy should be representable in memory during a session:

Current Session
└── Current Tire Stint
 └── Current Pace Segment
 └── Current Lap
 ├── Turn 1 complete
 ├── Turn 2 complete
 └── Turn 3 active
 ├── Entry complete
 ├── Apex active
 └── Exit pending

Completed corners, laps, and runs can be analyzed while the session continues. The raw recorder remains the only live persistence writer.

Every important derived artifact should be traceable.

A provenance receipt should be able to answer:

• Which source recording or archive produced this result?
• What was the source hash?
• Which parser and source-frame version were used?
• Which telemetry catalog and canonical schema were used?
• Which detector, policy, rule, and configuration versions were active?
• Which participant, time, lap, and distance ranges are covered?
• Is the result current, stale, limited, corrupt, or impossible to rebuild?
• Was the replacement generation verified before activation?

Related artifacts should be activated as a consistent generation.

Validate source
 ↓
Build affected artifacts into staging
 ↓
Validate identities, references, counts, and coverage
 ↓
Write provenance receipt
 ↓
Atomically activate the new generation
 ↓
Retain or clean up the old generation

A failed rebuild must leave the previously active generation usable.

RaceIQ must not update laps, events, stints, findings, and reports independently in a way that mixes old and new interpretations of the same session.

current
stale_rebuild_available
stale_source_missing
rebuild_in_progress
verification_failed
incompatible
corrupt

A Parquet file merely existing is not enough to permit raw cleanup.

The canonical archive should first pass verification for:

• source identity and hash;
• expected session and participant identity;
• readable schema and partitions;
• row ordering and timestamp validity;
• lap/time/track-distance coverage;
• required channel inventory or explicit unavailability;
• representative Analyse and Compare reads;
• output hash and inventory;
• database activation state.

Only then should the raw recording become eligible for retention cleanup under #217.

Telemetry is a stream of samples. Some changes should become durable events.

Examples:

14:22.100 — caution started
14:24.870 — participant entered pit road
14:39.410 — participant reached pit stall
14:44.230 — tire service observed
14:45.100 — fuel increased by 18.2 L
14:49.780 — participant departed stall
15:03.340 — participant exited pit road

Downstream features should consume these stable events instead of independently detecting the same transition.

Initial event families should include:

• session and phase changes;
• green, caution, red, restart, and checkered transitions;
• lap and sector completion;
• pit entry, stall arrival, service, departure, and exit;
• tire, fuel, repair, and driver service;
• incidents, penalties, damage, resets, and retirement observations;
• participant availability and driver changes;
• source connection, gaps, duplicates, out-of-order data, and discontinuities.

Every event should retain enough information to answer:

• what happened;
• when and where it happened;
• which participant or driver it affected;
• whether it was observed, derived, or inferred;
• how confident RaceIQ is;
• which detector and version produced it;
• which analysis generation owns it.

Reprocessing the same source with the same rules should reproduce the same semantic event identities.

IDs should be based on meaningful coordinates such as:

• session identity;
• participant identity;
• timeline epoch;
• event type;
• source tick, time, or boundary;
• related lap or pit-visit identity.

They should not be based only on auto-increment database order or final display text.

A sequence of nearby lap numbers is not automatically one meaningful stint.

RaceIQ should preserve several related but separate run concepts.

A continuous observed period for one vehicle or participant.

A continuous interval where RaceIQ has evidence that the same tire set remained fitted.

Pit entry by itself must not create a new tire stint.

A continuous interval driven by one driver.

A driver change does not necessarily imply a tire change.

A set of laps that can reasonably share a pace baseline.

A fuel-only stop, major repair, reset, red-flag restart, or explicit analysis boundary may create a new pace segment without creating a new tire stint.

The laps within a run that are eligible for a particular calculation.

Caution, incident, traffic, pit, and degraded-data laps should remain visible in the run. They can be excluded from one calculation without being deleted from the session record.

Tire Stint 2 — Medium compound — 20 laps
├── Pace Segment A — laps 1–12 — green run
├── Fuel-only stop
└── Pace Segment B — laps 14–20 — green run

This context prevents future models from treating every sequence of adjacent lap numbers as one equivalent training series.

These are separate questions.

Possible states include:

exact
minor_gaps
degraded
incomplete
incompatible
corrupt
unavailable

Measurements can include:

• expected versus observed samples;
• duplicate and out-of-order observations;
• total missing fraction;
• largest contiguous gap;
• reconnect count;
• timeline discontinuities;
• writer or storage drops;
• clean versus interrupted shutdown;
• canonical archive verification.

This is the #229 classification layer.

A classification describes what happened. It does not decide every possible use of the telemetry.

Each channel should retain applicable information such as:

• direct, normalized, derived, simplified, or unavailable mapping;
• canonical and native unit;
• expected and observed freshness;
• source cadence;
• stale, missing, invalid, not-applicable, or error state;
• interpolation or fallback use;
• simulator or car limitations;
• lost detail and element ordering.

Eligibility must be evaluated for a declared purpose.

Examples include:

official-timing
normal-pace
lap-comparison
corner-trace
transient-event
fuel-burn
tire-analysis
stint-falloff
setup-analysis
driver-profile
ml-training

Each policy returns something equivalent to:

eligible
eligible_with_warning
ineligible
unknown

The result should include:

• policy identity and version;
• reason codes;
• evidence references;
• affected time or distance ranges;
• channel limitations;
• confidence.

A single lap may therefore be:

Official timing: eligible
Normal pace: eligible
Lap comparison: eligible
Corner trace: eligible
Transient event: ineligible at Turn 4
Fuel burn: eligible
Tire analysis: unknown
ML training: eligible only for selected targets

This is the central rule for future ML data selection:

Training eligibility is task-specific, not equivalent to "lap exists" or "lap is valid."

Quality should be attached to the range it affects.

For example:

100 ms gap on a straight
 lap timing: eligible
 Turn 4 corner trace: unaffected
 transient detection inside the gap: ineligible
1 second gap through the apex
 lap timing: possibly retained with warning
 Turn 4 racing line: ineligible
 fuel burn: possibly still eligible

The system should avoid invalidating an entire session or lap when only one analysis range is affected.

RaceIQ should distinguish measurement, finding, recommendation, and narrative.

Turn 4 throttle pickup: 71.8% of corner distance
Reference pickup: 65.2%
Difference: +6.6 percentage points

Type: throttle_pickup_late
Scope: Turn 4
Status: available
Confidence: high
Evidence: laps 8, 10, 11, 12, and 14

Finish rotation earlier and begin a progressive
throttle application closer to the apex.

You're waiting too long to get back to power in Turn 4.
The car is already rotated, so begin squeezing the
throttle sooner rather than adding more steering.

The narrative may be generated by deterministic templates or an AI model. The measurements and finding identity must remain unchanged when the wording changes.

Not every analysis attempt should force a conclusion.

available
unavailable
indeterminate

Examples:

Finding: tire_wear_progression
Status: unavailable
Reason: source does not provide usable tire-wear evidence

Finding: setup_change_effect
Status: indeterminate
Reason: driver line variation exceeds the measured setup effect

Unavailable and indeterminate results are useful because they stop UI and AI consumers from filling the gap with guesses.

AI should receive:

• structured findings;
• exact measurements and units;
• confidence;
• severity;
• evidence identities;
• unavailable or indeterminate results;
• quality limitations;
• approved recommendation candidates.

AI may:

• prioritize findings for a user's question;
• explain them naturally;
• combine related findings into a coaching plan;
• answer follow-up questions;
• tailor wording and drills.

AI must not:

• turn unknown into certainty;
• invent missing telemetry;
• create nonexistent corners or laps;
• claim causation when the evidence shows only correlation;
• change the stable finding identity.

A deterministic report should remain possible without any AI provider.

A finding becoming available does not mean RaceIQ should immediately interrupt the driver.

Live communication should follow a separate pipeline:

Event or finding
 ↓
Callout candidate
 ↓
Priority, confidence, freshness, context,
duplicate, cooldown, and workload arbitration
 ↓
Selected or suppressed decision
 ↓
Message rendering
 ↓
UI or voice delivery
 ↓
Delivery audit

Examples of suppression reasons include:

expired
stale_source
source_invalidated
wrong_session_or_epoch
insufficient_confidence
ineligible_evidence
context_blocked
semantic_duplicate
cooldown_active
lower_priority_in_cohort
queue_capacity
muted_by_user
feature_disabled
shadow_only
unsupported_delivery

New live rules should be capable of running in shadow mode:

• generate real candidates;
• run the production arbitration policy;
• record selected and suppressed decisions;
• produce no user-visible or spoken output;
• allow developers to inspect false positives, timing, conflicts, and frequency.

This is also the appropriate deployment model for future learned predictions. A model should first prove useful and safe in offline and shadow evaluation before influencing the driver.

The same selected decision may be rendered in different ways:

"You're within three tenths of class pace."
"Pace is good—three tenths from the class benchmark."

Changing wording, localization, voice, or personality should not change:

• the source event or finding;
• whether the candidate was selected;
• duplicate suppression;
• cooldown identity;
• decision provenance.

RaceIQ should be able to process the same session through several paths:

Live-style source processing
Raw recording replay
Raw-to-canonical archive conversion
Canonical archive-only rebuild

These paths have different operational behavior, but they should agree on the same semantic racing facts.

Parity should eventually cover:

• canonical telemetry;
• lap identity and timing;
• lap classification;
• telemetry quality and eligibility;
• race events;
• tire, driver, participant, and pace runs;
• corner and segment ranges;
• deterministic findings;
• live-engineer shadow decisions;
• provenance receipts and artifact inventories.

Parity does not mean every incidental field must be identical.

Fields such as these may be intentionally excluded:

• database auto-increment IDs;
• absolute local paths;
• process IDs;
• actual wall-clock processing duration;
• actual historical voice playback;
• AI-generated prose.

Stable semantic identities, classifications, reason codes, event ordering, run boundaries, evidence references, and algorithm versions should match exactly or according to a narrowly documented numeric tolerance.

A hash failure by itself is not enough. The parity tooling should report the first differing:

• processing path;
• artifact family;
• stable identity;
• field;
• expected and actual value;
• source tick, time, lap, or distance range;
• schema, detector, policy, and configuration version.

Tier 1 — focused unit and contract tests
Tier 2 — short fixture live-versus-raw parity
Tier 3 — canonical archive conversion and rebuild parity
Tier 4 — long-session, interruption, recovery, and release validation

Golden recordings from #241 and their manifests from #242 should explain what each fixture is intended to prove.

Consider a completed Lap 12.

RaceIQ recorded the source frames into the normal .bin.gz recording.

Phase: flying
Conditions: green
Pace eligibility: eligible

Recording lifecycle: minor_gaps
Largest gap: 100 ms
Gap location: straight before Turn 4
Speed coverage: 99.7%
Throttle coverage: 99.8%
Position coverage: 100%
Tire wear: pit-only updates

Official timing: eligible
Normal pace: eligible
Lap comparison: eligible
Turn 4 corner trace: eligible
Transient analysis during gap range: ineligible
Fuel burn: eligible
Continuous tire trend: ineligible
ML training for lap-pace model: eligible
ML training for wheel-slip detector: ineligible

No caution overlap
No pit-lane overlap
No incident event
Tire stint: 2
Driver stint: 1
Pace segment: 2A

Session 42
└── Participant local-player
 └── Pace Segment 2A
 └── Lap 12
 └── Turn 4
 ├── Braking range
 ├── Entry range
 ├── Apex range
 └── Exit range

Type: throttle_pickup_late
Scope: Turn 4
Status: available
Confidence: high
Reference: clean-lap median
Evidence: laps 8, 10, 11, 12, and 14

This allows RaceIQ to use the same evidence in Analyse, Compare, a deterministic report, an AI explanation, and a future training dataset without each consumer inventing its own filters.

The ML preparation branch has reached the point where it should be treated as an integration and reference implementation.

It is ready to be decomposed into focused PRs. It should not be merged as one giant branch.

The first focused extraction is the #236 quality core/foundation work. The important goal is that each PR branch starts from the latest main rather than being based on the previous feature PR.

That produces independent review branches while the integration branch can continue combining them for full-stack testing.

#236 quality foundation
 ↓
#234 race-event timeline
 ↓
#235 session runs and pace segments
 ↓
#233 provenance receipts and generations
 ↓
#232 canonical archive and hierarchy
 ↓
#237 deterministic findings
 ↓
#239 complete parity harness

#229 classification should be introduced where its minimum contract is required, then completed with event-assisted classification and downstream behavior as the relevant foundations land.

#238 should remain a later phase because it depends on stable events, quality decisions, runs, and findings.

Include:

• shared quality contracts;
• stable quality and eligibility reason codes;
• deterministic quality measurement;
• gap and coverage handling;
• reusable eligibility policies;
• source fidelity and participant evidence;
• quality generation and version identity;
• focused persistence and invalidation;
• focused tests.

Only include the minimum #229 classification contract required by quality policies.

Avoid pulling in the complete rebuild coordinator, broad UI changes, Setup Engineer integration, or AI consumption until the lower-level contract is reviewable on its own.

Include:

• event contracts and payload validation;
• stable event identities;
• deterministic ordering and timeline epochs;
• focused detectors;
• timeline coordinator;
• game-specific adapters where required;
• persistence and typed queries;
• reset, reconnect, replay, and interruption behavior;
• focused tests.

When the full diff remains too large, split it into:

1. event contracts, identities, ordering, detectors, and coordinator;
2. persistence, rebuild, API, projections, and UI.

Complete or verify:

• out-lap detection;
• in-lap detection;
• pit-lap behavior;
• grid-start detection;
• caution, formation, and slow-zone context;
• default exclusion from normal pace;
• preservation for other analyses;
• API and UI exposure;
• replay parity.

Include:

• shared run contracts;
• participant, tire, driver, and pace-run kinds;
• stable run identity;
• event-backed boundaries;
• lap membership;
• boundary reasons and confidence;
• summaries;
• live and replay finalization behavior;
• focused persistence and tests.

This should come after #234 because event IDs and event ordering are the boundary evidence for the runs.

Include:

• provenance receipt contracts;
• canonical hashing;
• source and output inventories;
• artifact-set generations;
• staging, failure, superseding, and activation behavior;
• stale-state detection;
• rebuild preview and status;
• focused activation, rollback, and recovery tests.

A large user-facing provenance panel can remain a later PR if the backend contract is already substantial.

• archive schema and manifest;
• archive, job, and receipt tables;
• job claiming and lease behavior;
• stable archive identity;
• verification contracts.

• raw capture iteration;
• replay through parser and canonical resolution;
• bounded DuckDB/Parquet writing;
• file publication;
• verification;
• retry and failure handling;
• provenance receipt activation.

• participant → stint → lap → corner → segment indexes;
• archive-backed Analyse and Compare reads;
• availability APIs;
• verified raw-retention gate;
• user-facing archive state.

First PR:

• finding contracts;
• measurement definitions;
• stable finding identity;
• available, unavailable, and indeterminate states;
• deterministic rules;
• persistence;
• focused tests.

Later PR:

• Analyse and Compare UI;
• Setup Engineer adapters;
• deterministic reports;
• AI grounding and prompt inputs;
• driver-profile consumption.

Land after durable events, quality decisions, runs, and findings provide stable evidence.

Begin with:

• candidate contracts;
• deterministic arbitration;
• precise suppression reasons;
• semantic duplicate handling;
• shared cooldowns;
• shadow mode;
• deterministic rendering;
• delivery audit.

Do not begin by enabling a large set of spoken messages.

Parity coverage should be added alongside every domain PR.

The final #239 work should connect those focused tests into the complete:

live-style processing
 ↕
raw replay
 ↕
archive conversion
 ↕
archive-only rebuild

fixture harness.

Because the issues have broad acceptance criteria, early PRs should normally use:

Part of #236

or:

Progress toward #236

Do not use Closes #236 until the complete issue acceptance criteria are genuinely satisfied.

The detailed runtime, model packaging, distribution, update, personalization, and training architecture is documented on the companion page: RaceIQ Machine Learning Runtime, Distribution, Training, and Personalization.

Issues #229 and #232–#239 create most of the trusted evidence foundation, but they do not by themselves constitute a complete machine-learning program.

Additional ML-specific work will still be required.

A versioned dataset builder must convert stable RaceIQ scopes into training examples.

A future example record will likely need concepts such as:

example_id
dataset_version
source_generation
session_id
participant_id
scope_kind
lap / stint / corner / segment IDs
telemetry range references
feature definition version
label definition version
quality and eligibility references
car / track / conditions context
grouping and split identity
consent / permitted-use state

Features need stable names, units, derivation versions, and missing-value behavior.

Examples might include:

• braking onset distance;
• brake release rate;
• peak brake pressure;
• minimum corner speed;
• turn-in location;
• apex location;
• throttle pickup point;
• full-throttle point;
• steering correction count;
• path deviation;
• corner time;
• tire-state trend;
• fuel-adjusted pace;
• early, middle, and late stint pace;
• degradation slope;
• traffic, incident, and caution context.

A model input must retain whether a value was direct, derived, simplified, interpolated, or unavailable.

RaceIQ needs a declared label contract rather than treating every derived number as a label.

Potential label sources include:

• deterministic measurements;
• stable race events;
• simulator-provided outcomes;
• comparison against a selected reference;
• verified setup changes;
• user-confirmed feedback;
• later expert review.

Human feedback must remain distinguishable from telemetry-derived evidence.

For example, after a tire-pressure adjustment, RaceIQ could ask:

Why did you make this adjustment?
Did it improve the problem?
What problem were you trying to correct?

A response such as "tight in the center, and the pressure change helped" could become a human-provided label linked to:

• the exact setup generation;
• the pre-change and post-change pace segments;
• the relevant corners;
• the user's consent state;
• objective telemetry measurements;
• the confidence and source of the feedback.

RaceIQ should preserve both the user's report and the telemetry outcome. It should not automatically treat either one as absolute ground truth.

Training, validation, and test sets should be grouped so that nearly identical laps from the same session do not appear on both sides of an evaluation.

Depending on the task, grouping may need to occur by:

• session;
• source recording;
• driver;
• event;
• car and track;
• setup generation;
• time period;
• simulator or source type.

The split strategy must be versioned as part of the dataset definition.

Before a complex model is accepted, RaceIQ should compare it against simple deterministic or statistical baselines.

Evaluation may need:

• error by simulator;
• error by car and track;
• error by evidence quality;
• confidence calibration;
• false-positive and false-negative rates;
• performance on unseen drivers or sessions;
• stability across parser, schema, and dataset versions;
• comparison against deterministic findings;
• shadow-mode usefulness and distraction rate for live features.

A deployed prediction should retain:

• model ID and version;
• training dataset version;
• feature definition version;
• inference configuration;
• input evidence identities;
• quality and eligibility state;
• prediction confidence;
• shadow or enabled state;
• downstream decision outcome.

A prediction should initially run offline or in shadow mode. It should not directly bypass the deterministic live-engineer arbitration layer.

Data collection for training will need a separate user-facing policy covering:

• whether telemetry may be used;
• whether human feedback may be used;
• local-only versus shared training;
• anonymization or pseudonymization;
• retention duration;
• withdrawal and deletion;
• whether already trained models can be affected by a deletion request;
• export and audit behavior.

That policy should be designed before collecting user data for centralized training.

The foundation can be considered ready for serious dataset and model work when:

• Every supported telemetry value has a stable semantic meaning and declared fidelity.
• Source, session, participant, vehicle, and driver identities are explicit.
• Non-pace lap classification is separate from structural validity.
• Quality is measured by source, channel, lap, time range, and track-distance range.
• Every analysis uses a shared, versioned eligibility policy.
• Missing, unavailable, simplified, derived, and stale values remain distinguishable.
• Events provide stable context for cautions, pits, incidents, service, resets, and source failures.
• Tire, driver, participant, and pace runs have stable identities and boundary reasons.
• Canonical archives can preserve required historical analysis without a second live writer.
• Derived artifacts retain source, version, configuration, generation, and verification provenance.
• Findings cite exact evidence and remain separate from AI-generated wording.
• Live candidates can be evaluated in shadow mode before user-facing delivery.
• Live, raw replay, archive conversion, and rebuild pass the declared semantic parity contract.
• Golden recordings and manifests cover the required games and lifecycle scenarios.
• A versioned dataset builder defines examples, labels, exclusions, and split groups.
• User consent and data-retention rules are enforced before data enters a training dataset.
• Model predictions are versioned, auditable, confidence-aware, and safely deployable.

When reviewing this architecture or one of its PRs, ask:

1. Is this introducing a second definition of an existing fact?
   A new consumer should normally use the shared classification, event, run, quality, or finding contract rather than redetecting it.

2. Can the result explain where it came from?
   Derived records should identify their source evidence, scope, rules, versions, and limitations.

3. Does missing information remain unknown?
   Unavailable telemetry must not silently become zero, false, clean, or confidently inferred.

4. Will live, replay, and rebuild use the same domain implementation?
   Separate code paths must not produce incompatible meanings.

5. Can failure leave the system in a mixed generation?
   Rebuilds and imports should stage, verify, and activate atomically.

6. Is the PR independently reviewable from current main?
   The beta branch should remain an integration/reference implementation rather than forcing reviewers through a stacked chain.

7. Would this data be safe to use for training?
   The answer should name the exact eligibility policy, label origin, provenance, split grouping, and consent state rather than relying on an informal "clean lap" assumption.

Simulator-independent telemetry with stable meanings and units.

The most authoritative retained input, such as a raw RaceIQ recording, native import, or verified external source.

A persisted result calculated from source evidence, such as laps, events, stints, findings, or reports.

A description of what kind of lap or range occurred, such as flying, out, in, pit, grid start, or caution.

A structured description of a recording, channel, lap, or range limitation, including severity, affected scope, and evidence.

A versioned rule that determines whether evidence is suitable for a declared purpose.

A durable structured transition such as caution start, pit entry, tire service, source reconnect, or lap completion.

A group of laps that can reasonably share one pace baseline, even when the surrounding tire or driver stint continues.

A structured deterministic interpretation supported by measurements and evidence.

One internally consistent version of a session's related derived artifacts.

The record explaining which source, versions, configuration, outputs, and verification produced an artifact generation.

Running real production decision logic while suppressing user-visible delivery so behavior can be evaluated safely.

Agreement on stable racing facts across live processing, raw replay, archive conversion, and rebuild, excluding explicitly documented runtime-only details.

The current ML preparation work is mature enough to be separated into independently reviewable foundations.

The correct next phase is not to keep adding more major systems to the beta branch. The beta branch should remain the integration/reference implementation while focused branches are cut from the latest main and merged in dependency order.

The immediate starting point is the #236 quality core. Once quality, events, runs, provenance, archives, and findings are independently reviewable and parity-tested, RaceIQ will have the stable evidence base needed for serious dataset construction and machine-learning experimentation.