@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/raceSimulation.js

@@ -1,1146 +1,520 @@
 import {
-  buildTrackModel,
-  createProceduralTrack,
-  nearestTrackState,
-  offsetTrackPoint,
-  pointAt,
-  TRACK,
-  WORLD,
-} from './trackModel.js';
-import { buildDriverPersonality, decideDriverControls } from './driverController.js';
-import { clamp, createMulberry32, normalizeAngle, seededRange, wrapDistance } from './simMath.js';
-import { simSpeedToKph, simUnitsToMeters } from './units.js';
-import { getCarCorners, integrateVehiclePhysics, VEHICLE_LIMITS } from './vehiclePhysics.js';
-
-const DEFAULT_TOTAL_LAPS = 10;
-export const FIXED_STEP = 1 / 60;
-const MIN_TOTAL_LAPS = 1;
-const MAX_COLLISION_CORRECTION = 4.5;
-const GRID_SLOT_SPACING = 82;
-const GRID_FIRST_SLOT_DISTANCE = -42;
-const GRID_LATERAL_OFFSET = 42;
-const TIMING_HISTORY_WINDOW_SECONDS = 18;
-const TIMING_HISTORY_MAX_SAMPLES = 720;
-const TELEMETRY_SECTOR_COUNT = 3;
-
-export const DEFAULT_RULES = {
-  drsDetectionSeconds: 1,
-  safetyCarSpeed: 46,
-  safetyCarLeadDistance: 122,
-  safetyCarGap: 128,
-  collisionRestitution: 0.18,
-  standingStart: true,
-  startLightCount: 5,
-  startLightInterval: 0.72,
-  startLightsOutHold: 0.78,
-};
-
-function wrapProgress(value, length) {
-  return wrapDistance(value, length);
-}
+  applyUnservedServicePenalty,
+  cancelPenaltyRecord,
+  createPenaltyEvent,
+  createPenaltyRecord,
+  servePenaltyRecord,
+} from './rules/penaltyLedger.js';
+import { createPenaltyCancelledEvent, createPenaltyServedEvent } from './rules/penaltyEvents.js';
+import { buildPenaltyStatsByDriver, getPenaltyStats } from './rules/penaltyStats.js';
+import {
+  reviewCollisionForSimulation,
+  reviewPitLaneSpeedingForSimulation,
+  reviewTireRequirementForSimulation,
+  reviewTrackLimitsForSimulation,
+} from './rules/rulesReview.js';
+import { DEFAULT_RULES } from './rulesConfig.js';
+import { applyExternalCarState } from './vehicle/vehicleState.js';
+import {
+  applyContactVelocityResponse as applyContactVelocityResponseForSimulation,
+  resolveCollisionsForSimulation,
+} from './vehicle/contactResolution.js';
+import { applyRunoffResponseForSimulation } from './vehicle/runoffResponse.js';
+import { resetLapTelemetry, resetTimingHistory, resetTimingLineCrossings } from './timing/raceTiming.js';
+import { updateDrsLatch as updateDrsLatchState } from './timing/drsTiming.js';
+import {
+  PIT_INTENT_NONE,
+  setPitIntentForSimulation,
+} from './pit/pitIntent.js';
+import { assignPitLaneTeams as assignPitLaneTeamsState, initializePitStops as initializePitStopsState } from './pit/pitState.js';
+import {
+  applyPitRoutePosition as applyPitRoutePositionForSimulation,
+  beginPitPenaltyService as beginPitPenaltyServiceForSimulation,
+  beginPitQueue as beginPitQueueForSimulation,
+  beginPitService as beginPitServiceForSimulation,
+  beginTireService as beginTireServiceForSimulation,
+  calculatePitServiceProfile as calculatePitServiceProfileForSimulation,
+  completePitPenaltyService as completePitPenaltyServiceForSimulation,
+  completePitService as completePitServiceForSimulation,
+  finishPitExit as finishPitExitForSimulation,
+  getPitBoxRaceDistance as getPitBoxRaceDistanceForSimulation,
+  getPitServicePenalties as getPitServicePenaltiesForSimulation,
+  getPitStopBox as getPitStopBoxForSimulation,
+  isPitServiceAreaOccupied as isPitServiceAreaOccupiedForSimulation,
+  isPitServiceBusy as isPitServiceBusyForSimulation,
+  isPitServiceQueueOccupied as isPitServiceQueueOccupiedForSimulation,
+  releasePitQueue as releasePitQueueForSimulation,
+} from './pit/pitService.js';
+import {
+  advancePitStopCar as advancePitStopCarForSimulation,
+  canStartPitStop as canStartPitStopForSimulation,
+  isCarInActivePitStop as isCarInActivePitStopForSimulation,
+  isPitLaneOpenForStops as isPitLaneOpenForStopsForSimulation,
+  pitEntryLateThresholdDistance as pitEntryLateThresholdDistanceForSimulation,
+  rearmCompletedPitStop as rearmCompletedPitStopForSimulation,
+  schedulePitStopAtNextEntry as schedulePitStopAtNextEntryForSimulation,
+  shouldStartPitStop as shouldStartPitStopForSimulation,
+  startPitStop as startPitStopForSimulation,
+  updateAutomaticPitIntent as updateAutomaticPitIntentForSimulation,
+} from './pit/pitFlow.js';
+import { nearestDistanceOnRoute } from './pit/pitRouting.js';
+import {
+  moveSafetyCarTo as moveSafetyCarToState,
+  setRedFlagState,
+  setSafetyCarState,
+  updateSafetyCarState,
+} from './race/safetyCar.js';
+import {
+  holdGridCars as holdGridCarsForSimulation,
+  releaseRaceStart as releaseRaceStartForSimulation,
+  setPitLaneOpenState,
+  updateStartSequence as updateStartSequenceForSimulation,
+} from './race/raceLifecycle.js';
+import {
+  applyClassificationConsequences as applyClassificationConsequencesState,
+  applyOutstandingServicePenalties as applyOutstandingServicePenaltiesState,
+  buildClassification as buildClassificationState,
+  buildClassificationFromFinishOrder as buildClassificationFromFinishOrderState,
+} from './race/classification.js';
+import {
+  computeAggressionForSimulation,
+  driverRaceContextForSimulation,
+  getDrsReferenceCarForSimulation,
+  orderedCarsForSimulation,
+} from './race/raceOrder.js';
+import {
+  computeLapForDistance,
+  finishDistanceForRace,
+  progressDelta,
+} from './race/raceDistance.js';
+import { recalculateRaceStateForSimulation } from './race/raceProgress.js';
+import { evaluateRaceFinishForSimulation } from './race/raceFinish.js';
+import { applyGridDropForSimulation } from './race/gridPenalties.js';
+import { initializeRaceSimulation, normalizePitIntentForRace } from './race/raceSetup.js';
+import { runRaceStep } from './race/raceStep.js';
+import {
+  createVehicleSnapshotDependencies,
+  getRaceWinnerSnapshot as getRaceWinnerSnapshotForSimulation,
+  snapshotRace,
+  snapshotRaceObservation,
+  snapshotRaceRender,
+  snapshotRaceTraining,
+} from './snapshots/raceSnapshots.js';
+import {
+  disableWarmupOptions,
+  runWarmupWithGuard,
+  withWarmupSurfaceOptions,
+} from './warmup/runtimeWarmup.js';
 
-function distanceForward(from, to, length) {
-  return wrapProgress(to - from, length);
-}
+export const FIXED_STEP = 1 / 60;
 
-function crossesDistance(previous, current, target, length) {
-  const travelled = distanceForward(previous, current, length);
-  if (travelled <= 0 || travelled > length / 2) return false;
-  const targetOffset = distanceForward(previous, target, length);
-  return targetOffset > 0 && targetOffset <= travelled + 0.001;
-}
+export { DEFAULT_RULES };
 
-function isProgressInZone(track, progress, zone) {
-  const wrapped = wrapProgress(progress, track.length);
-  const start = wrapProgress(zone.start, track.length);
-  const end = wrapProgress(zone.end, track.length);
-  if (zone.end - zone.start >= track.length) return true;
-  return end >= start
-    ? wrapped >= start && wrapped <= end
-    : wrapped >= start || wrapped <= end;
-}
+export class F1RaceSimulation {
+  constructor(options = {}) {
+    initializeRaceSimulation(this, options);
+  }
 
-function createEmptySectorTimes() {
-  return Array.from({ length: TELEMETRY_SECTOR_COUNT }, () => null);
-}
+  assignPitLaneTeams() {
+    assignPitLaneTeamsState({ cars: this.cars, pitLane: this.track.pitLane });
+  }
 
-function createEmptySectorPerformance() {
-  return {
-    current: createEmptySectorTimes(),
-    last: createEmptySectorTimes(),
-    best: createEmptySectorTimes(),
-  };
-}
+  initializePitStops() {
+    initializePitStopsState({
+      cars: this.cars,
+      pitLane: this.track.pitLane,
+      pitStops: this.rules.modules?.pitStops,
+      totalLaps: this.totalLaps,
+      trackLength: this.track.length,
+      tireCompounds: this.rules.modules?.tireStrategy?.compounds,
+      PIT_INTENT_NONE,
+    });
+  }
 
-function getSectorLength(track) {
-  return track.length / TELEMETRY_SECTOR_COUNT;
-}
+  setSafetyCar(deployed) {
+    setSafetyCarState(this, deployed);
+  }
 
-function getLapTelemetryPosition(track, raceDistance, totalLaps = Infinity) {
-  const positiveDistance = Math.max(0, raceDistance ?? 0);
-  const lapIndex = Math.min(
-    Math.floor(positiveDistance / track.length),
-    Math.max(0, totalLaps - 1),
-  );
-  const lapProgress = positiveDistance >= track.length * totalLaps
-    ? track.length
-    : positiveDistance - lapIndex * track.length;
-  const sectorLength = getSectorLength(track);
-  const sectorIndex = Math.min(TELEMETRY_SECTOR_COUNT - 1, Math.floor(lapProgress / sectorLength));
-  const sectorStart = sectorIndex * sectorLength;
-
-  return {
-    completedLaps: Math.floor(positiveDistance / track.length),
-    currentLap: Math.max(1, lapIndex + 1),
-    currentSector: sectorIndex + 1,
-    currentSectorProgress: clamp((lapProgress - sectorStart) / sectorLength, 0, 1),
-  };
-}
+  setRedFlag(deployed) {
+    setRedFlagState(this, deployed);
+  }
 
-function createLapTelemetry(track, currentTime = 0, raceDistance = 0, totalLaps = Infinity) {
-  const position = getLapTelemetryPosition(track, raceDistance, totalLaps);
-  return {
-    ...position,
-    currentLapStartedAt: currentTime,
-    currentSectorStartedAt: currentTime,
-    lastUpdatedAt: currentTime,
-    currentLapTime: 0,
-    currentSectorElapsed: 0,
-    currentSectors: createEmptySectorTimes(),
-    lastLapTime: null,
-    bestLapTime: null,
-    lastSectors: createEmptySectorTimes(),
-    bestSectors: createEmptySectorTimes(),
-    sectorPerformance: createEmptySectorPerformance(),
-  };
-}
+  setPitLaneOpen(open) {
+    setPitLaneOpenState(this, open);
+  }
 
-function resetLapTelemetry(car, currentTime, track, totalLaps) {
-  car.lapTelemetry = createLapTelemetry(track, currentTime, car.raceDistance, totalLaps);
-}
+  setCarState(id, partial) {
+    this.setCarStates({ [id]: partial });
+  }
 
-function finiteOrNull(value) {
-  return Number.isFinite(value) ? value : null;
-}
+  setCarStates(partialsById = {}) {
+    const context = {
+      cars: this.cars,
+      computeLap: (raceDistance) => this.computeLap(raceDistance),
+      nearestDistanceOnRoute,
+      progressDelta,
+      raceControl: this.raceControl,
+      releaseRaceStart: () => this.releaseRaceStart(),
+      resetLapTelemetry,
+      resetTimingHistory,
+      resetTimingLineCrossings,
+      time: this.time,
+      totalLaps: this.totalLaps,
+      track: this.track,
+    };
+    let applied = false;
+    Object.entries(partialsById).forEach(([id, partial]) => {
+      const car = this.cars.find((item) => item.id === id);
+      if (!car) return;
+      applyExternalCarState(car, partial, context);
+      applied = true;
+    });
+    if (!applied) return;
+    this.recalculateRaceState({ updateDrs: false });
+    this.evaluateRaceFinish();
+  }
 
-function serializeSectorTimes(values) {
-  return createEmptySectorTimes().map((_, index) => finiteOrNull(values?.[index]));
-}
+  setCarControls(id, controls) {
+    const car = this.cars.find((item) => item.id === id);
+    if (!car) return;
+    car.manualControls = controls;
+  }
 
-function serializeLapTelemetry(telemetry) {
-  return {
-    currentLap: telemetry.currentLap,
-    currentSector: telemetry.currentSector,
-    currentLapTime: finiteOrNull(telemetry.currentLapTime),
-    currentSectorElapsed: finiteOrNull(telemetry.currentSectorElapsed),
-    currentSectorProgress: finiteOrNull(telemetry.currentSectorProgress),
-    currentSectors: serializeSectorTimes(telemetry.currentSectors),
-    lastLapTime: finiteOrNull(telemetry.lastLapTime),
-    bestLapTime: finiteOrNull(telemetry.bestLapTime),
-    lastSectors: serializeSectorTimes(telemetry.lastSectors),
-    bestSectors: serializeSectorTimes(telemetry.bestSectors),
-    sectorPerformance: {
-      current: serializeSectorPerformance(telemetry.sectorPerformance?.current),
-      last: serializeSectorPerformance(telemetry.sectorPerformance?.last),
-      best: serializeSectorPerformance(telemetry.sectorPerformance?.best),
-    },
-    completedLaps: telemetry.completedLaps,
-  };
-}
+  clearCarControls(id) {
+    const car = this.cars.find((item) => item.id === id);
+    if (car) car.manualControls = null;
+  }
 
-function serializeSectorPerformance(values) {
-  return createEmptySectorTimes().map((_, index) => values?.[index] ?? null);
-}
+  setAutomaticPitIntentEnabled(id, enabled) {
+    const car = this.cars.find((item) => item.id === id);
+    if (!car) return false;
+    car.automaticPitIntentEnabled = Boolean(enabled);
+    return true;
+  }
 
-function updateBestSector(telemetry, sectorIndex, sectorTime) {
-  const previousBest = telemetry.bestSectors[sectorIndex];
-  if (!Number.isFinite(previousBest) || sectorTime < previousBest) {
-    telemetry.bestSectors[sectorIndex] = sectorTime;
+  getPitIntent(id) {
+    const car = this.cars.find((item) => item.id === id);
+    return normalizePitIntentForRace(car);
   }
-}
 
-function syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps) {
-  const position = getLapTelemetryPosition(track, currentRaceDistance, totalLaps);
-  telemetry.currentLap = position.currentLap;
-  telemetry.currentSector = position.currentSector;
-  telemetry.currentSectorProgress = position.currentSectorProgress;
-  telemetry.completedLaps = Math.max(telemetry.completedLaps, Math.min(position.completedLaps, totalLaps));
-  telemetry.currentLapTime = Math.max(0, currentTime - telemetry.currentLapStartedAt);
-  telemetry.currentSectorElapsed = Math.max(0, currentTime - telemetry.currentSectorStartedAt);
-}
+  getPitTargetCompound(id) {
+    const car = this.cars.find((item) => item.id === id);
+    return car?.pitStop?.targetTire ?? null;
+  }
 
-function classifySectorPerformance(value, personalBest, overallBest) {
-  if (!Number.isFinite(value)) return null;
-  if (Number.isFinite(overallBest) && Math.abs(value - overallBest) <= 1e-6) return 'overall-best';
-  if (Number.isFinite(personalBest) && Math.abs(value - personalBest) <= 1e-6) return 'personal-best';
-  return 'slower';
-}
+  setPitIntent(id, intent, targetCompound = undefined) {
+    return setPitIntentForSimulation(this, id, intent, targetCompound);
+  }
 
-function updateSectorPerformance(cars) {
-  const overallBestSectors = createEmptySectorTimes();
-  cars.forEach((car) => {
-    car.lapTelemetry?.bestSectors?.forEach((time, index) => {
-      if (!Number.isFinite(time)) return;
-      const previousBest = overallBestSectors[index];
-      if (!Number.isFinite(previousBest) || time < previousBest) overallBestSectors[index] = time;
-    });
-  });
+  isCarInActivePitStop(car) {
+    return isCarInActivePitStopForSimulation(this, car);
+  }
 
-  cars.forEach((car) => {
-    if (!car.lapTelemetry) return;
-    const telemetry = car.lapTelemetry;
-    telemetry.sectorPerformance = {
-      current: telemetry.currentSectors.map((time, index) => (
-        classifySectorPerformance(time, telemetry.bestSectors[index], overallBestSectors[index])
-      )),
-      last: telemetry.lastSectors.map((time, index) => (
-        classifySectorPerformance(time, telemetry.bestSectors[index], overallBestSectors[index])
-      )),
-      best: telemetry.bestSectors.map((time, index) => (
-        classifySectorPerformance(time, telemetry.bestSectors[index], overallBestSectors[index])
-      )),
-    };
-  });
-}
+  schedulePitStopAtNextEntry(car, stop) {
+    return schedulePitStopAtNextEntryForSimulation(this, car, stop);
+  }
 
-function updateLapTelemetry(car, previousRaceDistance, currentTime, track, totalLaps) {
-  if (!car.lapTelemetry) resetLapTelemetry(car, currentTime, track, totalLaps);
-
-  const telemetry = car.lapTelemetry;
-  const currentRaceDistance = car.raceDistance ?? 0;
-  const previousDistance = Math.max(0, previousRaceDistance ?? currentRaceDistance);
-  const currentDistance = Math.max(0, currentRaceDistance);
-  const travelled = currentDistance - previousDistance;
-  const previousUpdateTime = Number.isFinite(telemetry.lastUpdatedAt) ? telemetry.lastUpdatedAt : currentTime;
-  const elapsedTime = Math.max(0, currentTime - previousUpdateTime);
-
-  if (!Number.isFinite(previousDistance) || !Number.isFinite(currentDistance) || travelled < -1e-3 || travelled > track.length / 2) {
-    resetLapTelemetry(car, currentTime, track, totalLaps);
-    return;
-  }
-
-  const sectorLength = getSectorLength(track);
-  if (travelled > 1e-6) {
-    const firstBoundary = Math.floor(previousDistance / sectorLength) + 1;
-    const lastBoundary = Math.floor(currentDistance / sectorLength);
-
-    for (let boundary = firstBoundary; boundary <= lastBoundary; boundary += 1) {
-      const boundaryDistance = boundary * sectorLength;
-      if (boundaryDistance <= previousDistance + 1e-3 || boundaryDistance > currentDistance + 1e-3) continue;
-
-      const boundaryRatio = clamp((boundaryDistance - previousDistance) / travelled, 0, 1);
-      const crossingTime = previousUpdateTime + boundaryRatio * elapsedTime;
-      const sectorIndex = (boundary - 1) % TELEMETRY_SECTOR_COUNT;
-      const sectorTime = Math.max(0, crossingTime - telemetry.currentSectorStartedAt);
-
-      telemetry.currentSectors[sectorIndex] = sectorTime;
-      updateBestSector(telemetry, sectorIndex, sectorTime);
-
-      if (sectorIndex === TELEMETRY_SECTOR_COUNT - 1) {
-        const lapTime = Math.max(0, crossingTime - telemetry.currentLapStartedAt);
-        telemetry.lastLapTime = lapTime;
-        telemetry.bestLapTime = Number.isFinite(telemetry.bestLapTime)
-          ? Math.min(telemetry.bestLapTime, lapTime)
-          : lapTime;
-        telemetry.lastSectors = serializeSectorTimes(telemetry.currentSectors);
-        telemetry.currentSectors = createEmptySectorTimes();
-        telemetry.currentLapStartedAt = crossingTime;
-        telemetry.completedLaps = Math.max(telemetry.completedLaps + 1, Math.min(Math.floor(boundaryDistance / track.length), totalLaps));
-      }
-
-      telemetry.currentSectorStartedAt = crossingTime;
-    }
+  rearmCompletedPitStop(car, stop) {
+    return rearmCompletedPitStopForSimulation(this, car, stop);
   }
 
-  syncLapTelemetryPosition(telemetry, currentTime, currentRaceDistance, track, totalLaps);
-  telemetry.lastUpdatedAt = currentTime;
-}
+  canStartPitStop(car) {
+    return canStartPitStopForSimulation(this, car);
+  }
 
-function createCar(driver, index, random, track, { standingStart = false } = {}) {
-  const gridDistance = GRID_FIRST_SLOT_DISTANCE - index * GRID_SLOT_SPACING;
-  const start = pointAt(track, gridDistance);
-  const offset = index % 2 === 0 ? -GRID_LATERAL_OFFSET : GRID_LATERAL_OFFSET;
-  const position = offsetTrackPoint(start, offset);
-  const pace = clamp(driver.pace ?? seededRange(random, 0.95, 1.05), 0.88, 1.12);
-  const racecraft = clamp(driver.racecraft ?? seededRange(random, 0.65, 0.92), 0.45, 1);
-  const personality = buildDriverPersonality(driver, index, racecraft, random);
-  const launchSpeed = Math.max(70, 84 - index * 0.55 + pace * 4);
-  const vehicle = driver.vehicle ?? {};
-
-  return {
-    id: driver.id ?? `car-${index + 1}`,
-    code: driver.code ?? `C${index + 1}`,
-    timingCode: driver.timingCode ?? driver.code ?? `C${index + 1}`,
-    driverNumber: driver.driverNumber ?? index + 1,
-    icon: driver.icon ?? String(index + 1).padStart(2, '0'),
-    raceName: driver.raceName ?? driver.code ?? `CAR${index + 1}`,
-    name: driver.name ?? `Car ${index + 1}`,
-    color: driver.color ?? '#e10600',
-    team: driver.team ? { ...driver.team } : null,
-    tire: driver.tire ?? ['M', 'H', 'S'][index % 3],
-    index,
-    x: position.x,
-    y: position.y,
-    previousX: position.x,
-    previousY: position.y,
-    heading: start.heading,
-    previousHeading: start.heading,
-    steeringAngle: 0,
-    yawRate: 0,
-    turnRadius: Infinity,
-    speed: standingStart ? 0 : launchSpeed,
-    throttle: 0,
-    brake: 0,
-    vehicleId: vehicle.id ?? null,
-    vehicleName: vehicle.name ?? null,
-    vehicleRatings: vehicle.ratings ? { ...vehicle.ratings } : null,
-    mass: vehicle.mass ?? 798 + seededRange(random, -5, 5),
-    powerNewtons: vehicle.powerNewtons ?? 43000 * pace,
-    brakeNewtons: vehicle.brakeNewtons ?? 59000,
-    dragCoefficient: vehicle.dragCoefficient ?? 0.33 + seededRange(random, -0.026, 0.026),
-    downforceCoefficient: vehicle.downforceCoefficient ?? 6.1 + seededRange(random, -0.18, 0.18),
-    tireGrip: vehicle.tireGrip ?? 2.22 + racecraft * 0.28 + seededRange(random, -0.03, 0.03),
-    tireCare: vehicle.tireCare ?? 1,
-    pace,
-    racecraft,
-    personality,
-    aggression: personality.baseAggression,
-    gridLocked: standingStart,
-    gridDistance,
-    gridOffset: offset,
-    desiredOffset: offset,
-    progress: start.distance,
-    raceDistance: gridDistance,
-    lap: 1,
-    rank: index + 1,
-    gapAhead: Infinity,
-    gapAheadSeconds: Infinity,
-    leaderGapSeconds: 0,
-    intervalAheadSeconds: Infinity,
-    drsEligible: false,
-    drsActive: false,
-    drsZoneId: null,
-    drsZoneEnabled: false,
-    timingHistory: [],
-    lapTelemetry: createLapTelemetry(track, 0, gridDistance),
-    drsDetection: {},
-    canAttack: true,
-    trackState: start,
-    contactCooldown: 0,
-    tireEnergy: 100,
-  };
-}
+  shouldStartPitStop(car) {
+    return shouldStartPitStopForSimulation(this, car);
+  }
 
-function normalizeTotalLaps(value) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return MIN_TOTAL_LAPS;
-  return Math.max(MIN_TOTAL_LAPS, Math.floor(numeric));
-}
+  updateAutomaticPitIntent(car) {
+    return updateAutomaticPitIntentForSimulation(this, car);
+  }
 
-function projectOntoAxis(points, axis) {
-  let min = Infinity;
-  let max = -Infinity;
-  points.forEach((point) => {
-    const projection = point.x * axis.x + point.y * axis.y;
-    min = Math.min(min, projection);
-    max = Math.max(max, projection);
-  });
-  return { min, max };
-}
+  isPitLaneOpenForStops() {
+    return isPitLaneOpenForStopsForSimulation(this);
+  }
 
-function overlapOnAxis(a, b, axis) {
-  const first = projectOntoAxis(a, axis);
-  const second = projectOntoAxis(b, axis);
-  return Math.min(first.max, second.max) - Math.max(first.min, second.min);
-}
+  pitEntryLateThresholdDistance() {
+    return pitEntryLateThresholdDistanceForSimulation();
+  }
 
-function detectObbCollision(a, b) {
-  const aCorners = getCarCorners(a);
-  const bCorners = getCarCorners(b);
-  const axes = [
-    normalizeVector({ x: aCorners[1].x - aCorners[0].x, y: aCorners[1].y - aCorners[0].y }),
-    normalizeVector({ x: aCorners[3].x - aCorners[0].x, y: aCorners[3].y - aCorners[0].y }),
-    normalizeVector({ x: bCorners[1].x - bCorners[0].x, y: bCorners[1].y - bCorners[0].y }),
-    normalizeVector({ x: bCorners[3].x - bCorners[0].x, y: bCorners[3].y - bCorners[0].y }),
-  ];
-
-  let minimumOverlap = Infinity;
-  let minimumAxis = null;
-
-  for (const axis of axes) {
-    const overlap = overlapOnAxis(aCorners, bCorners, axis);
-    if (overlap <= 0) return null;
-    if (overlap < minimumOverlap) {
-      minimumOverlap = overlap;
-      minimumAxis = axis;
-    }
+  getPitStopBox(stop) {
+    return getPitStopBoxForSimulation(this, stop);
   }
 
-  const direction = { x: b.x - a.x, y: b.y - a.y };
-  if (direction.x * minimumAxis.x + direction.y * minimumAxis.y < 0) {
-    minimumAxis = { x: -minimumAxis.x, y: -minimumAxis.y };
+  isPitServiceBusy(car, box) {
+    return isPitServiceBusyForSimulation(this, car, box);
   }
 
-  return { axis: minimumAxis, depth: minimumOverlap };
-}
+  isPitServiceAreaOccupied(candidate, box) {
+    return isPitServiceAreaOccupiedForSimulation(this, candidate, box);
+  }
 
-function detectLongitudinalCollision(a, b) {
-  const longitudinalGap = b.raceDistance - a.raceDistance;
-  const headingDelta = Math.abs(normalizeAngle(a.heading - b.heading));
-  const blendedHeading = a.heading + normalizeAngle(b.heading - a.heading) * 0.5;
-  let axis = normalizeVector({ x: Math.cos(blendedHeading), y: Math.sin(blendedHeading) });
-  const direction = { x: b.x - a.x, y: b.y - a.y };
-  const physicalLongitudinalGap = dot(direction, axis);
-  if (physicalLongitudinalGap < 0) axis = { x: -axis.x, y: -axis.y };
-
-  const physicalLongitudinalSeparation = Math.abs(physicalLongitudinalGap);
-  const lateralGap = Math.abs(direction.x * -axis.y + direction.y * axis.x);
-  const requiredGap = VEHICLE_LIMITS.carLength * 0.96;
-
-  if (Math.abs(longitudinalGap) > VEHICLE_LIMITS.carLength * 1.45) return null;
-  if (physicalLongitudinalSeparation >= requiredGap) return null;
-  if (lateralGap > VEHICLE_LIMITS.carWidth * 0.82) return null;
-  if (headingDelta > 0.58) return null;
-
-  return {
-    axis,
-    depth: requiredGap - physicalLongitudinalSeparation,
-    longitudinal: true,
-  };
-}
+  isPitServiceQueueOccupied(car, box) {
+    return isPitServiceQueueOccupiedForSimulation(this, car, box);
+  }
 
-function forwardVector(car) {
-  return { x: Math.cos(car.heading), y: Math.sin(car.heading) };
-}
+  getPitBoxRaceDistance(stop, box) {
+    return getPitBoxRaceDistanceForSimulation(this, stop, box);
+  }
 
-function dot(a, b) {
-  return a.x * b.x + a.y * b.y;
-}
+  startPitStop(car) {
+    return startPitStopForSimulation(this, car);
+  }
 
-function normalizeVector(vector) {
-  const length = Math.hypot(vector.x, vector.y) || 1;
-  return { x: vector.x / length, y: vector.y / length };
-}
+  beginPitQueue(car, box) {
+    return beginPitQueueForSimulation(this, car, box);
+  }
 
-function progressDelta(a, b, trackLength) {
-  let delta = a - b;
-  if (delta < -trackLength / 2) delta += trackLength;
-  if (delta > trackLength / 2) delta -= trackLength;
-  return delta;
-}
+  releasePitQueue(car, box, { fromCurrent = false } = {}) {
+    return releasePitQueueForSimulation(this, car, box, { fromCurrent });
+  }
 
-function trimTimingHistory(history, currentTime) {
-  const cutoff = currentTime - TIMING_HISTORY_WINDOW_SECONDS;
-  while (history.length > 2 && (history[0].time < cutoff || history.length > TIMING_HISTORY_MAX_SAMPLES)) {
-    history.shift();
+  beginPitService(car, box) {
+    return beginPitServiceForSimulation(this, car, box);
   }
-}
 
-function resetTimingHistory(car, currentTime) {
-  car.timingHistory = [{ time: currentTime, raceDistance: car.raceDistance }];
-}
+  beginPitPenaltyService(car) {
+    return beginPitPenaltyServiceForSimulation(this, car);
+  }
 
-function recordTimingSample(car, currentTime) {
-  if (!Number.isFinite(car.raceDistance)) return;
-  if (!Array.isArray(car.timingHistory)) {
-    resetTimingHistory(car, currentTime);
-    return;
+  calculatePitServiceProfile(car) {
+    return calculatePitServiceProfileForSimulation(this, car);
   }
 
-  const previous = car.timingHistory[car.timingHistory.length - 1];
-  if (
-    previous &&
-    Math.abs(previous.time - currentTime) <= 1e-6 &&
-    Math.abs(previous.raceDistance - car.raceDistance) <= 1e-3
-  ) {
-    return;
+  beginTireService(car) {
+    return beginTireServiceForSimulation(this, car);
   }
 
-  car.timingHistory.push({ time: currentTime, raceDistance: car.raceDistance });
-  trimTimingHistory(car.timingHistory, currentTime);
-}
+  completePitPenaltyService(car) {
+    return completePitPenaltyServiceForSimulation(this, car);
+  }
 
-function interpolateTimeAtDistance(history, targetDistance) {
-  if (!Array.isArray(history) || history.length < 2) return null;
+  getPitServicePenalties(driverId) {
+    return getPitServicePenaltiesForSimulation(this, driverId);
+  }
 
-  for (let index = history.length - 1; index > 0; index -= 1) {
-    const current = history[index];
-    const previous = history[index - 1];
-    if (targetDistance < previous.raceDistance || targetDistance > current.raceDistance) continue;
+  completePitService(car) {
+    return completePitServiceForSimulation(this, car);
+  }
 
-    const coveredDistance = current.raceDistance - previous.raceDistance;
-    if (coveredDistance <= 1e-6) return current.time;
-    const ratio = (targetDistance - previous.raceDistance) / coveredDistance;
-    return previous.time + (current.time - previous.time) * ratio;
+  finishPitExit(car) {
+    return finishPitExitForSimulation(this, car);
   }
 
-  return null;
-}
+  applyPitRoutePosition(car, delta) {
+    return applyPitRoutePositionForSimulation(this, car, delta);
+  }
 
-function estimateGapAheadSeconds(ahead, car, currentTime) {
-  if (!ahead) return Infinity;
+  advancePitStopCar(car, delta) {
+    return advancePitStopCarForSimulation(this, car, delta);
+  }
 
-  const crossingTime = interpolateTimeAtDistance(ahead.timingHistory, car.raceDistance);
-  if (Number.isFinite(crossingTime)) {
-    return Math.max(0, currentTime - crossingTime);
+  step(dt) {
+    runRaceStep(this, dt);
   }
 
-  const speedReference = Math.max((ahead.speed + car.speed) * 0.5, 1);
-  return Math.max(0, (ahead.raceDistance - car.raceDistance) / speedReference);
-}
+  recordPenalty(penalty) {
+    const car = this.cars.find((item) => item.id === penalty.driverId);
+    const entry = createPenaltyRecord({
+      sequence: this.nextPenaltyId,
+      time: this.time,
+      lap: this.computeLap(car?.raceDistance ?? 0),
+      penalty,
+    });
+    this.nextPenaltyId += 1;
+    this.penalties.push(entry);
+    if (entry.gridDrop > 0 && this.raceControl.mode === 'pre-start') {
+      this.applyGridDrop(entry.driverId, entry.gridDrop);
+    }
+    this.events.unshift(createPenaltyEvent(entry));
+    return entry;
+  }
 
-function recordDrsDetection(car, zoneId, currentTime) {
-  const previous = car.drsDetection?.[zoneId] ?? { passage: 0, time: -Infinity };
-  const next = { passage: previous.passage + 1, time: currentTime };
-  car.drsDetection = {
-    ...(car.drsDetection ?? {}),
-    [zoneId]: next,
-  };
-  return next;
-}
+  servePenalty(penaltyId) {
+    const penalty = this.penalties.find((entry) => entry.id === penaltyId);
+    const result = servePenaltyRecord(penalty, this.time);
+    if (result) {
+      this.events.unshift(createPenaltyServedEvent(result, this.time));
+    }
+    return result;
+  }
 
-function serializeCar(car, rank) {
-  return {
-    id: car.id,
-    code: car.code,
-    timingCode: car.timingCode,
-    driverNumber: car.driverNumber,
-    icon: car.icon,
-    raceName: car.raceName,
-    name: car.name,
-    color: car.color,
-    team: car.team ? { ...car.team } : null,
-    tire: car.tire,
-    personality: { ...car.personality },
-    aggression: car.aggression,
-    aggressionPercent: Math.round((car.aggression ?? 0) * 100),
-    setup: {
-      vehicleId: car.vehicleId,
-      vehicleName: car.vehicleName,
-      vehicleRatings: car.vehicleRatings ? { ...car.vehicleRatings } : null,
-      maxSpeedKph: simSpeedToKph(VEHICLE_LIMITS.maxSpeed),
-      powerUnitKn: car.powerNewtons / 1000,
-      brakeSystemKn: car.brakeNewtons / 1000,
-      dragCoefficient: car.dragCoefficient,
-      downforceCoefficient: car.downforceCoefficient,
-      tireGrip: car.tireGrip,
-      tireCare: car.tireCare,
-      massKg: car.mass,
-      pace: car.pace,
-      racecraft: car.racecraft,
-    },
-    rank,
-    classifiedRank: car.classifiedRank ?? rank,
-    finished: Boolean(car.finished),
-    finishTime: car.finishTime ?? null,
-    previousX: car.previousX ?? car.x,
-    previousY: car.previousY ?? car.y,
-    x: car.x,
-    y: car.y,
-    previousHeading: car.previousHeading ?? car.heading,
-    heading: car.heading,
-    steeringAngle: car.steeringAngle,
-    yawRate: car.yawRate,
-    turnRadius: car.turnRadius,
-    speed: car.speed,
-    speedKph: simSpeedToKph(car.speed),
-    throttle: car.throttle,
-    brake: car.brake,
-    lateralAcceleration: car.lateralAcceleration,
-    progress: car.progress,
-    raceDistance: car.raceDistance,
-    distanceMeters: simUnitsToMeters(car.raceDistance),
-    lap: car.lap,
-    lapTelemetry: serializeLapTelemetry(car.lapTelemetry ?? createLapTelemetry({ length: 1 }, 0, 0)),
-    gapAhead: car.gapAhead,
-    gapAheadMeters: Number.isFinite(car.gapAhead) ? simUnitsToMeters(car.gapAhead) : Infinity,
-    gapAheadSeconds: car.gapAheadSeconds,
-    intervalAheadSeconds: car.intervalAheadSeconds,
-    leaderGapSeconds: car.leaderGapSeconds,
-    drsEligible: car.drsEligible,
-    drsActive: car.drsActive,
-    drsZoneId: car.drsZoneId,
-    drsZoneEnabled: car.drsZoneEnabled,
-    canAttack: car.canAttack,
-    signedOffset: car.trackState?.signedOffset ?? 0,
-    crossTrackError: car.trackState?.crossTrackError ?? 0,
-    surface: car.trackState?.surface ?? 'track',
-    contactCooldown: car.contactCooldown,
-    tireEnergy: car.tireEnergy,
-    positionSource: 'integrated-vehicle',
-  };
-}
+  cancelPenalty(penaltyId) {
+    const penalty = this.penalties.find((entry) => entry.id === penaltyId);
+    const result = cancelPenaltyRecord(penalty, this.time);
+    if (result) {
+      this.events.unshift(createPenaltyCancelledEvent(result, this.time));
+    }
+    return result;
+  }
 
-export class F1RaceSimulation {
-  constructor({ seed = 1, drivers = [], totalLaps = DEFAULT_TOTAL_LAPS, rules = {}, track = null, trackSeed = null } = {}) {
-    this.seed = seed;
-    this.random = createMulberry32(seed);
-    const trackDefinition = track ?? (trackSeed == null ? TRACK : createProceduralTrack(trackSeed));
-    this.track = buildTrackModel(trackDefinition);
-    this.trackSeed = this.track.seed ?? trackSeed;
-    this.rules = { ...DEFAULT_RULES, ...rules };
-    this.startLightsOutAt = this.rules.startLightCount * this.rules.startLightInterval + this.rules.startLightsOutHold;
-    this.totalLaps = normalizeTotalLaps(totalLaps);
-    this.time = 0;
-    this.events = [];
-    this.raceControl = {
-      mode: this.rules.standingStart === false ? 'green' : 'pre-start',
-      frozenOrder: null,
-      finished: false,
-      finishedAt: null,
-      winnerId: null,
-      classification: [],
-      finishOrder: [],
-      start: {
-        lightCount: this.rules.startLightCount,
-        lightsLit: 0,
-        lightsOutAt: this.startLightsOutAt,
-        released: this.rules.standingStart === false,
-        releasedAt: this.rules.standingStart === false ? 0 : null,
-      },
-    };
-    const safetyCarStart = pointAt(this.track, this.rules.safetyCarLeadDistance);
-    this.safetyCar = {
-      deployed: false,
-      progress: this.rules.safetyCarLeadDistance,
-      speed: this.rules.safetyCarSpeed,
-      previousX: safetyCarStart.x,
-      previousY: safetyCarStart.y,
-      previousHeading: safetyCarStart.heading,
-      x: safetyCarStart.x,
-      y: safetyCarStart.y,
-      heading: safetyCarStart.heading,
-    };
-    this.cars = drivers.map((driver, index) => createCar(driver, index, this.random, this.track, {
-      standingStart: this.raceControl.mode === 'pre-start',
-    }));
-    this.recalculateRaceState({ updateDrs: false });
-    this.cars.forEach((car) => resetTimingHistory(car, this.time));
-    this.cars.forEach((car) => resetLapTelemetry(car, this.time, this.track, this.totalLaps));
+  getDriverPenaltySeconds(driverId) {
+    return getPenaltyStats(this.getPenaltyStatsByDriver(), driverId).seconds;
   }
 
-  setSafetyCar(deployed) {
-    const next = Boolean(deployed);
-    if (this.raceControl.finished) return;
-    if (next && this.raceControl.mode === 'pre-start') return;
-    if (next === this.safetyCar.deployed) return;
-    const ordered = this.orderedCars();
-    this.safetyCar.deployed = next;
-    this.raceControl.mode = next ? 'safety-car' : 'green';
-    this.raceControl.frozenOrder = next ? ordered.map((car) => car.id) : null;
-    if (next) {
-      const leader = ordered[0];
-      const safetyCarProgress = (leader?.raceDistance ?? 0) + this.rules.safetyCarLeadDistance;
-      if (this.safetyCar.progress < safetyCarProgress) {
-        this.moveSafetyCarTo(safetyCarProgress);
-      }
-      this.cars.forEach((car) => {
-        car.desiredOffset = 0;
-        car.drsActive = false;
-        car.drsEligible = false;
-        car.drsZoneId = null;
-        car.drsZoneEnabled = false;
-      });
-    }
-    this.events.unshift({ type: next ? 'safety-car' : 'green-flag', at: this.time });
+  getDriverPositionDrop(driverId) {
+    return getPenaltyStats(this.getPenaltyStatsByDriver(), driverId).positionDrop;
   }
 
-  setCarState(id, partial) {
-    const car = this.cars.find((item) => item.id === id);
-    if (!car) return;
-    Object.assign(car, partial);
-    if (
-      partial.x != null ||
-      partial.y != null ||
-      partial.progress != null ||
-      partial.raceDistance != null
-    ) {
-      car.gridLocked = false;
-      if (this.raceControl.mode === 'pre-start' && this.cars.every((item) => !item.gridLocked)) {
-        this.releaseRaceStart();
-      }
-    }
-    car.speed = clamp(car.speed, 0, VEHICLE_LIMITS.maxSpeed);
-    car.heading = normalizeAngle(car.heading);
-    car.trackState = nearestTrackState(this.track, car);
-    const delta = progressDelta(car.trackState.distance, car.progress ?? car.trackState.distance, this.track.length);
-    car.raceDistance = (car.raceDistance ?? car.trackState.distance) + delta;
-    car.progress = car.trackState.distance;
-    car.lap = this.computeLap(car.raceDistance);
-    car.drsZoneId = null;
-    car.drsZoneEnabled = false;
-    car.drsActive = false;
-    car.drsEligible = false;
-    car.drsDetection = {};
-    resetTimingHistory(car, this.time);
-    resetLapTelemetry(car, this.time, this.track, this.totalLaps);
-    this.recalculateRaceState({ updateDrs: false });
-    this.evaluateRaceFinish();
+  isDriverDisqualified(driverId) {
+    return getPenaltyStats(this.getPenaltyStatsByDriver(), driverId).disqualified;
   }
 
-  setCarControls(id, controls) {
-    const car = this.cars.find((item) => item.id === id);
-    if (!car) return;
-    car.manualControls = controls;
+  getPenaltyStatsByDriver() {
+    return buildPenaltyStatsByDriver(this.penalties);
   }
 
-  clearCarControls(id) {
-    const car = this.cars.find((item) => item.id === id);
-    if (car) car.manualControls = null;
+  applyGridDrop(driverId, positions) {
+    applyGridDropForSimulation(this, driverId, positions);
   }
 
-  step(dt) {
-    const delta = clamp(dt, 0, 1 / 20);
-    if (!Number.isFinite(delta) || delta <= 0) return;
+  reviewCollision(first, second, collision) {
+    reviewCollisionForSimulation(this, first, second, collision);
+  }
 
-    this.time += delta;
-    this.events = [];
-    this.updateStartSequence();
-    this.recalculateRaceState({ updateDrs: false });
+  reviewTireRequirement(car) {
+    if (this.stewardState.tireRequirement[car.id]) return;
+    this.stewardState.tireRequirement[car.id] = true;
+    reviewTireRequirementForSimulation(this, car);
+  }
 
-    if (this.raceControl.mode === 'pre-start' && this.cars.every((car) => car.gridLocked)) {
-      this.holdGridCars();
-      this.recalculateRaceState({ updateDrs: false });
-      return;
-    }
+  reviewTrackLimits() {
+    reviewTrackLimitsForSimulation(this);
+  }
 
-    this.updateSafetyCar(delta);
-
-    const orderedCars = this.orderedCars();
-    const raceContext = this.driverRaceContext(orderedCars);
-    orderedCars.forEach((car, index) => {
-      car.previousX = car.x;
-      car.previousY = car.y;
-      car.previousHeading = car.heading;
-      car.previousProgress = car.progress;
-      const controls = decideDriverControls({
-        car,
-        orderIndex: index,
-        race: raceContext,
-      });
-      integrateVehiclePhysics(car, controls, delta);
-      this.applyRunoffResponse(car);
-      car.contactCooldown = Math.max(0, car.contactCooldown - delta);
-    });
+  reviewPitLaneSpeeding() {
+    reviewPitLaneSpeedingForSimulation(this);
+  }
 
-    this.resolveCollisions();
-    this.recalculateRaceState();
-    this.evaluateRaceFinish();
+  vehicleSnapshotDependencies() {
+    return createVehicleSnapshotDependencies(this);
   }
 
   snapshot() {
-    const ordered = this.orderedCars();
-    return {
-      time: this.time,
-      world: WORLD,
-      track: this.track,
-      totalLaps: this.totalLaps,
-      raceControl: {
-        mode: this.raceControl.mode,
-        finished: this.raceControl.finished,
-        finishedAt: this.raceControl.finishedAt,
-        winner: this.getRaceWinnerSnapshot(),
-        classification: this.raceControl.classification.map((entry) => ({ ...entry })),
-        start: {
-          ...this.raceControl.start,
-          visible: this.raceControl.mode === 'pre-start' ||
-            (this.raceControl.start.releasedAt != null && this.time - this.raceControl.start.releasedAt < 1.45),
-        },
-      },
-      safetyCar: { ...this.safetyCar },
-      rules: this.rules,
-      events: [...this.events],
-      cars: ordered.map((car, index) => serializeCar(car, index + 1)),
-    };
+    return snapshotRace(this);
   }
 
-  orderedCars() {
-    if (this.safetyCar.deployed && this.raceControl.frozenOrder?.length) {
-      const byId = new Map(this.cars.map((car) => [car.id, car]));
-      return this.raceControl.frozenOrder.map((id) => byId.get(id)).filter(Boolean);
-    }
-
-    return [...this.cars].sort((a, b) => {
-      const delta = b.raceDistance - a.raceDistance;
-      return delta === 0 ? a.index - b.index : delta;
-    });
+  snapshotRender() {
+    return snapshotRaceRender(this);
   }
 
-  driverRaceContext(orderedCars = this.orderedCars()) {
-    return {
-      track: this.track,
-      cars: this.cars,
-      orderedCars,
-      safetyCar: this.safetyCar,
-      rules: this.rules,
-    };
+  snapshotObservation() {
+    return snapshotRaceObservation(this);
   }
 
-  computeAggression(car, orderIndex = Math.max(0, (car.rank ?? 1) - 1)) {
-    const personality = car.personality ?? { baseAggression: 0.5, riskTolerance: 0.5, patience: 0.5 };
-    if (this.safetyCar.deployed || car.canAttack === false) {
-      return clamp(personality.baseAggression * 0.62, 0.08, 0.62);
-    }
+  snapshotTraining() {
+    return snapshotRaceTraining(this);
+  }
 
-    const fieldDepth = Math.max(1, this.cars.length - 1);
-    const positionPressure = clamp(orderIndex / fieldDepth, 0, 1);
-    const gapPressure = Number.isFinite(car.gapAhead) ? clamp((230 - car.gapAhead) / 230, 0, 1) : 0;
-    const tireConfidence = clamp(((car.tireEnergy ?? 100) - 42) / 58, 0, 1);
-    const patienceDamping = (1 - gapPressure) * personality.patience * 0.08;
+  consumeStepEvents() {
+    return [...this.events];
+  }
 
-    return clamp(
-      personality.baseAggression
-        + positionPressure * 0.26
-        + gapPressure * (0.1 + personality.riskTolerance * 0.08)
-        - (1 - tireConfidence) * 0.1
-        - patienceDamping,
-      0.08,
-      1,
-    );
+  orderedCars() {
+    return orderedCarsForSimulation(this);
   }
 
-  updateStartSequence() {
-    const start = this.raceControl.start;
-    if (this.raceControl.mode !== 'pre-start' || !start || start.released) return;
+  driverRaceContext(orderedCars = this.orderedCars()) {
+    return driverRaceContextForSimulation(this, orderedCars);
+  }
 
-    if (this.time >= start.lightsOutAt) {
-      this.releaseRaceStart();
-      this.events.unshift({ type: 'start-lights-out', at: this.time });
-      return;
-    }
+  computeAggression(car, orderIndex = Math.max(0, (car.rank ?? 1) - 1)) {
+    return computeAggressionForSimulation(this, car, orderIndex);
+  }
 
-    start.lightsLit = clamp(
-      Math.floor((this.time + Number.EPSILON) / this.rules.startLightInterval),
-      0,
-      start.lightCount,
-    );
+  updateStartSequence() {
+    return updateStartSequenceForSimulation(this);
   }
 
   releaseRaceStart() {
-    const start = this.raceControl.start;
-    this.raceControl.mode = 'green';
-    start.lightsLit = 0;
-    start.released = true;
-    start.releasedAt = this.time;
-    this.cars.forEach((car) => {
-      const wasGridLocked = car.gridLocked;
-      car.gridLocked = false;
-      const state = nearestTrackState(this.track, car, car.gridDistance);
-      car.trackState = state;
-      car.progress = state.distance;
-      if (wasGridLocked) car.raceDistance = car.gridDistance;
-      car.previousX = car.x;
-      car.previousY = car.y;
-      car.previousHeading = car.heading;
-    });
+    return releaseRaceStartForSimulation(this);
   }
 
   holdGridCars() {
-    this.cars.forEach((car) => {
-      if (!car.gridLocked) return;
-      const gridPoint = pointAt(this.track, car.gridDistance);
-      const position = offsetTrackPoint(gridPoint, car.gridOffset);
-      car.previousX = position.x;
-      car.previousY = position.y;
-      car.previousHeading = gridPoint.heading;
-      car.x = position.x;
-      car.y = position.y;
-      car.heading = gridPoint.heading;
-      car.speed = 0;
-      car.throttle = 0;
-      car.brake = 1;
-      car.steeringAngle = 0;
-      car.yawRate = 0;
-      car.turnRadius = Infinity;
-      car.progress = gridPoint.distance;
-      car.raceDistance = car.gridDistance;
-      car.trackState = nearestTrackState(this.track, car, car.gridDistance);
-    });
+    return holdGridCarsForSimulation(this);
   }
 
   updateSafetyCar(dt) {
-    if (!this.safetyCar.deployed) return;
-    const leader = this.orderedCars()[0];
-    const targetProgress = (leader?.raceDistance ?? 0) + this.rules.safetyCarLeadDistance;
-    const progress = Math.max(this.safetyCar.progress + this.safetyCar.speed * dt, targetProgress);
-    this.moveSafetyCarTo(progress);
+    updateSafetyCarState(this, dt);
   }
 
   moveSafetyCarTo(progress) {
-    const point = pointAt(this.track, progress);
-    this.safetyCar.previousX = this.safetyCar.x;
-    this.safetyCar.previousY = this.safetyCar.y;
-    this.safetyCar.previousHeading = this.safetyCar.heading;
-    this.safetyCar.progress = progress;
-    this.safetyCar.x = point.x;
-    this.safetyCar.y = point.y;
-    this.safetyCar.heading = point.heading;
+    moveSafetyCarToState(this, progress);
   }
 
   applyRunoffResponse(car) {
-    const state = nearestTrackState(this.track, car, car.progress);
-    const signedLimit = this.track.width / 2 + this.track.gravelWidth + this.track.runoffWidth;
-    const overshoot = Math.abs(state.signedOffset) - signedLimit;
-    if (overshoot <= 0) {
-      car.trackState = state;
-      return;
-    }
-
-    const side = Math.sign(state.signedOffset) || 1;
-    car.x -= state.normalX * side * overshoot;
-    car.y -= state.normalY * side * overshoot;
-    car.speed = clamp(car.speed * clamp(1 - overshoot * 0.012, 0.22, 0.86), 0, VEHICLE_LIMITS.maxSpeed);
-    car.heading = normalizeAngle(car.heading - side * clamp(overshoot * 0.0028, 0.018, 0.08));
-    car.trackState = nearestTrackState(this.track, car, state.distance);
+    applyRunoffResponseForSimulation(this, car);
   }
 
   recalculateRaceState({ updateDrs = true } = {}) {
-    this.cars.forEach((car) => {
-      const previousRaceDistance = car.raceDistance;
-      if (car.gridLocked) {
-        const gridPoint = pointAt(this.track, car.gridDistance);
-        car.trackState = nearestTrackState(this.track, car, car.gridDistance);
-        car.progress = gridPoint.distance;
-        car.raceDistance = car.gridDistance;
-        car.lap = 1;
-        resetLapTelemetry(car, this.time, this.track, this.totalLaps);
-        return;
-      }
-
-      car.trackState = nearestTrackState(this.track, car, car.progress);
-      const previousProgress = car.progress ?? car.trackState.distance;
-      const delta = progressDelta(car.trackState.distance, previousProgress, this.track.length);
-      car.raceDistance = (car.raceDistance ?? previousProgress) + delta;
-      car.progress = car.trackState.distance;
-      car.lap = this.computeLap(car.raceDistance);
-      updateLapTelemetry(car, previousRaceDistance, this.time, this.track, this.totalLaps);
-    });
-
-    updateSectorPerformance(this.cars);
-    this.cars.forEach((car) => recordTimingSample(car, this.time));
-
-    const ordered = this.orderedCars();
-    ordered.forEach((car, index) => {
-      const ahead = ordered[index - 1];
-      const gap = ahead ? ahead.raceDistance - car.raceDistance : Infinity;
-      car.rank = index + 1;
-      car.gapAhead = gap;
-      car.gapAheadSeconds = Number.isFinite(gap) ? estimateGapAheadSeconds(ahead, car, this.time) : Infinity;
-      car.intervalAheadSeconds = car.gapAheadSeconds;
-      car.leaderGapSeconds = ahead ? ahead.leaderGapSeconds + car.gapAheadSeconds : 0;
-      car.canAttack = !this.safetyCar.deployed && !car.finished;
-      car.aggression = this.computeAggression(car, index);
-      if (updateDrs) this.updateDrsLatch(car, ahead, index);
-    });
-    this.evaluateRaceFinish();
+    return recalculateRaceStateForSimulation(this, { updateDrs });
   }
 
   evaluateRaceFinish() {
-    if (this.raceControl.finished) return;
-    if (this.raceControl.mode === 'pre-start') return;
-
-    const ordered = this.orderedCars();
-    const newlyFinished = ordered.filter((car) => !car.finished && car.raceDistance >= this.finishDistance);
-    if (newlyFinished.length === 0) return;
-
-    newlyFinished.forEach((car) => {
-      car.finished = true;
-      car.finishTime = this.time;
-      car.classifiedRank = this.raceControl.finishOrder.length + 1;
-      this.raceControl.finishOrder.push(car.id);
-      if (!this.raceControl.winnerId) this.raceControl.winnerId = car.id;
-      car.drsActive = false;
-      car.drsEligible = false;
-      car.drsZoneId = null;
-      car.drsZoneEnabled = false;
-      car.canAttack = false;
-      this.events.unshift({
-        type: 'car-finish',
-        at: this.time,
-        carId: car.id,
-        rank: car.classifiedRank,
-        winnerId: this.raceControl.winnerId,
-      });
-    });
+    evaluateRaceFinishForSimulation(this);
+  }
 
-    if (!this.cars.every((car) => car.finished)) return;
-
-    const classification = this.buildClassificationFromFinishOrder();
-    this.raceControl.mode = 'safety-car';
-    this.raceControl.finished = true;
-    this.raceControl.finishedAt = this.time;
-    this.raceControl.classification = classification;
-    this.raceControl.frozenOrder = classification.map((entry) => entry.id);
-    this.safetyCar.deployed = true;
-    const leader = this.cars.find((car) => car.id === this.raceControl.winnerId) ?? ordered[0];
-    const safetyCarProgress = (leader?.raceDistance ?? 0) + this.rules.safetyCarLeadDistance;
-    if (this.safetyCar.progress < safetyCarProgress) {
-      this.moveSafetyCarTo(safetyCarProgress);
-    }
-    this.cars.forEach((car) => {
-      const classified = classification.find((entry) => entry.id === car.id);
-      car.classifiedRank = classified?.rank ?? car.rank;
-      car.desiredOffset = 0;
-      car.drsActive = false;
-      car.drsEligible = false;
-      car.drsZoneId = null;
-      car.drsZoneEnabled = false;
-      car.canAttack = false;
-    });
-    this.events.unshift({
-      type: 'race-finish',
-      at: this.time,
-      winnerId: this.raceControl.winnerId,
-      classification: classification.map((entry) => ({ id: entry.id, rank: entry.rank })),
-    });
+  applyOutstandingServicePenalties() {
+    applyOutstandingServicePenaltiesState(this, applyUnservedServicePenalty);
   }
 
   buildClassificationFromFinishOrder() {
-    const byId = new Map(this.cars.map((car) => [car.id, car]));
-    const ordered = this.raceControl.finishOrder
-      .map((id) => byId.get(id))
-      .filter(Boolean);
-    return this.buildClassification(ordered);
-  }
-
-  buildClassification(ordered = this.orderedCars()) {
-    const leaderDistance = ordered[0]?.raceDistance ?? 0;
-    return ordered.map((car, index) => ({
-      id: car.id,
-      code: car.code,
-      timingCode: car.timingCode,
-      name: car.name,
-      rank: index + 1,
-      raceDistance: car.raceDistance,
-      distanceMeters: simUnitsToMeters(car.raceDistance),
-      lap: this.computeLap(car.raceDistance),
-      lapsCompleted: clamp(Math.floor(Math.max(0, car.raceDistance) / this.track.length), 0, this.totalLaps),
-      gapMeters: simUnitsToMeters(Math.max(0, leaderDistance - car.raceDistance)),
-      gapSeconds: index === 0 ? 0 : car.leaderGapSeconds,
-      intervalSeconds: index === 0 ? 0 : car.intervalAheadSeconds,
-      finished: car.raceDistance >= this.finishDistance,
-      finishTime: car.finishTime ?? (car.raceDistance >= this.finishDistance ? this.time : null),
-    }));
+    return buildClassificationFromFinishOrderState(this);
   }
 
-  getRaceWinnerSnapshot() {
-    if (!this.raceControl.winnerId) return null;
-    const car = this.cars.find((item) => item.id === this.raceControl.winnerId);
-    if (!car) return null;
-    const rank = car.classifiedRank ?? car.rank ?? 1;
-    return serializeCar(car, rank);
-  }
-
-  updateDrsLatch(car, ahead, orderIndex) {
-    if (this.safetyCar.deployed || car.finished) {
-      car.drsEligible = false;
-      car.drsActive = false;
-      car.drsZoneId = null;
-      car.drsZoneEnabled = false;
-      return;
-    }
+  applyClassificationConsequences(ordered, penaltyStats = this.getPenaltyStatsByDriver()) {
+    return applyClassificationConsequencesState(this, ordered, penaltyStats);
+  }
 
-    const previousProgress = car.previousProgress ?? car.progress;
-    const currentZone = car.drsZoneId
-      ? this.track.drsZones.find((zone) => zone.id === car.drsZoneId)
-      : null;
+  buildClassification(ordered = this.orderedCars(), penaltyStats = this.getPenaltyStatsByDriver()) {
+    return buildClassificationState(this, ordered, penaltyStats);
+  }
 
-    if (currentZone && !isProgressInZone(this.track, car.progress, currentZone)) {
-      car.drsZoneId = null;
-      car.drsZoneEnabled = false;
-    }
+  getRaceWinnerSnapshot() {
+    return getRaceWinnerSnapshotForSimulation(this);
+  }
 
-    if (!car.drsZoneId) {
-      const crossedZone = this.track.drsZones.find((zone) => (
-        crossesDistance(previousProgress, car.progress, zone.start, this.track.length)
-      ));
-      if (crossedZone) {
-        car.drsZoneId = crossedZone.id;
-        const crossing = recordDrsDetection(car, crossedZone.id, this.time);
-        const aheadCrossing = ahead?.drsDetection?.[crossedZone.id];
-        car.drsZoneEnabled = Boolean(
-          orderIndex > 0 &&
-          aheadCrossing &&
-          aheadCrossing.passage === crossing.passage &&
-          crossing.time >= aheadCrossing.time &&
-          crossing.time - aheadCrossing.time <= this.rules.drsDetectionSeconds + 1e-6
-        );
-      }
-    }
+  getDrsReferenceCar(car) {
+    return getDrsReferenceCarForSimulation(this, car);
+  }
 
-    const activeZone = car.drsZoneId
-      ? this.track.drsZones.find((zone) => zone.id === car.drsZoneId)
-      : null;
-    const inLatchedZone = activeZone ? isProgressInZone(this.track, car.progress, activeZone) : false;
-    car.drsEligible = Boolean(car.drsZoneEnabled && inLatchedZone);
-    car.drsActive = car.drsEligible;
+  updateDrsLatch(car, ahead, hasReference = Boolean(ahead)) {
+    updateDrsLatchState(car, ahead, {
+      hasReference,
+      safetyCarDeployed: this.safetyCar.deployed,
+      time: this.time,
+      track: this.track,
+      rules: this.rules,
+    });
   }
 
   resolveCollisions() {
-    const reportedContacts = new Set();
-
-    for (let pass = 0; pass < 3; pass += 1) {
-      for (let i = 0; i < this.cars.length; i += 1) {
-        for (let j = i + 1; j < this.cars.length; j += 1) {
-          const first = this.cars[i];
-          const second = this.cars[j];
-          const collision = detectObbCollision(first, second) ?? detectLongitudinalCollision(first, second);
-          if (!collision) continue;
-
-          const correction = Math.min(
-            collision.depth / 2 + (collision.longitudinal ? 0.35 : 0.65),
-            MAX_COLLISION_CORRECTION,
-          );
-          first.x -= collision.axis.x * correction;
-          first.y -= collision.axis.y * correction;
-          second.x += collision.axis.x * correction;
-          second.y += collision.axis.y * correction;
-
-          this.applyContactVelocityResponse(first, second, collision.axis);
-
-          const yawNudge = clamp(collision.depth * 0.0025, 0.008, 0.035);
-          const freshContact = first.contactCooldown <= 0 && second.contactCooldown <= 0;
-          first.heading = normalizeAngle(first.heading - collision.axis.y * yawNudge);
-          second.heading = normalizeAngle(second.heading + collision.axis.y * yawNudge);
-          first.contactCooldown = 1;
-          second.contactCooldown = 1;
-
-          const contactKey = `${first.id}:${second.id}`;
-          if (freshContact && pass === 0 && !reportedContacts.has(contactKey)) {
-            reportedContacts.add(contactKey);
-            this.events.unshift({ type: 'contact', at: this.time, carId: first.id, otherCarId: second.id });
-          }
-        }
-      }
-    }
+    resolveCollisionsForSimulation(this);
   }
 
   applyContactVelocityResponse(first, second, axis) {
-    const firstForward = forwardVector(first);
-    const secondForward = forwardVector(second);
-    const firstNormal = dot(firstForward, axis);
-    const secondNormal = dot(secondForward, axis);
-    const relativeNormalVelocity = second.speed * secondNormal - first.speed * firstNormal;
-
-    if (relativeNormalVelocity < 0) {
-      const impulse = clamp(-relativeNormalVelocity * (0.34 + this.rules.collisionRestitution), 0, 16);
-      if (firstNormal > 0) first.speed = clamp(first.speed - impulse * firstNormal, 0, VEHICLE_LIMITS.maxSpeed);
-      if (secondNormal < 0) second.speed = clamp(second.speed + impulse * secondNormal, 0, VEHICLE_LIMITS.maxSpeed);
-    }
-
-    first.speed = clamp(first.speed * 0.997, 0, VEHICLE_LIMITS.maxSpeed);
-    second.speed = clamp(second.speed * 0.997, 0, VEHICLE_LIMITS.maxSpeed);
+    applyContactVelocityResponseForSimulation(this, first, second, axis);
   }
 
   computeLap(raceDistance) {
-    return clamp(Math.floor(Math.max(0, raceDistance) / this.track.length) + 1, 1, this.totalLaps);
+    return computeLapForDistance(raceDistance, this.track.length, this.totalLaps);
   }
 
   get finishDistance() {
-    return this.track.length * this.totalLaps;
+    return finishDistanceForRace(this.track.length, this.totalLaps);
   }
 }
 
 export function createRaceSimulation(options = {}) {
-  return new F1RaceSimulation(options);
+  const resolvedOptions = withWarmupSurfaceOptions(options, options?.warmup?.surface ?? 'simulation');
+  runWarmupWithGuard({
+    options: resolvedOptions,
+    surface: resolvedOptions.warmup.surface,
+    execute: ({ warmup }) => {
+      const warmupSimulation = new F1RaceSimulation(disableWarmupOptions(resolvedOptions, warmup.surface));
+      for (let index = 0; index < warmup.steps; index += 1) warmupSimulation.step(FIXED_STEP);
+    },
+  });
+  return new F1RaceSimulation(resolvedOptions);
 }