@inventure71/paddockjs 0.3.0 → 2.0.0

package/src/simulation/replay/replayGhosts.js

@@ -0,0 +1,128 @@
+import { clamp, lerp, normalizeAngle } from '../simMath.js';
+
+const DEFAULT_GHOST_COLOR = '#00ff84';
+const DEFAULT_GHOST_OPACITY = 0.35;
+
+export function normalizeReplayGhosts(replayGhosts = []) {
+  if (!Array.isArray(replayGhosts)) return [];
+  return replayGhosts
+    .map((ghost, index) => normalizeReplayGhost(ghost, index))
+    .filter(Boolean);
+}
+
+export function updateReplayGhosts(replayGhosts = [], timeSeconds = 0) {
+  replayGhosts.forEach((ghost) => {
+    const previous = {
+      x: ghost.x,
+      y: ghost.y,
+      heading: ghost.heading,
+    };
+    const sample = interpolateTrajectory(ghost.trajectory, timeSeconds);
+    Object.assign(ghost, {
+      previousX: Number.isFinite(previous.x) ? previous.x : sample.x,
+      previousY: Number.isFinite(previous.y) ? previous.y : sample.y,
+      previousHeading: Number.isFinite(previous.heading) ? previous.heading : sample.heading,
+      x: sample.x,
+      y: sample.y,
+      heading: sample.heading,
+      speedKph: sample.speedKph,
+      progressMeters: sample.progressMeters,
+      timeSeconds,
+    });
+  });
+}
+
+export function serializeReplayGhosts(replayGhosts = []) {
+  return replayGhosts.map((ghost) => ({
+    id: ghost.id,
+    label: ghost.label,
+    color: ghost.color,
+    opacity: ghost.opacity,
+    visible: ghost.visible,
+    previousX: ghost.previousX,
+    previousY: ghost.previousY,
+    x: ghost.x,
+    y: ghost.y,
+    previousHeading: ghost.previousHeading,
+    heading: ghost.heading,
+    speedKph: ghost.speedKph,
+    progressMeters: ghost.progressMeters,
+    timeSeconds: ghost.timeSeconds,
+    sensors: { ...ghost.sensors },
+  }));
+}
+
+function normalizeReplayGhost(ghost, index) {
+  if (!ghost || typeof ghost !== 'object') return null;
+  const trajectory = normalizeTrajectory(ghost.trajectory);
+  if (trajectory.length === 0) return null;
+  const id = String(ghost.id ?? `replay-ghost-${index + 1}`);
+  const initial = interpolateTrajectory(trajectory, 0);
+  return {
+    id,
+    label: String(ghost.label ?? id),
+    color: typeof ghost.color === 'string' && ghost.color ? ghost.color : DEFAULT_GHOST_COLOR,
+    opacity: clamp(Number(ghost.opacity ?? DEFAULT_GHOST_OPACITY), 0, 1),
+    visible: ghost.visible !== false,
+    trajectory,
+    sensors: {
+      detectableByRays: Boolean(ghost.sensors?.detectableByRays),
+      detectableAsNearby: Boolean(ghost.sensors?.detectableAsNearby),
+    },
+    previousX: initial.x,
+    previousY: initial.y,
+    x: initial.x,
+    y: initial.y,
+    previousHeading: initial.heading,
+    heading: initial.heading,
+    speedKph: initial.speedKph,
+    progressMeters: initial.progressMeters,
+    timeSeconds: 0,
+  };
+}
+
+function normalizeTrajectory(trajectory) {
+  if (!Array.isArray(trajectory)) return [];
+  return trajectory
+    .map((sample) => {
+      const timeSeconds = finiteNumber(sample?.timeSeconds);
+      const x = finiteNumber(sample?.x);
+      const y = finiteNumber(sample?.y);
+      const heading = finiteNumber(sample?.headingRadians ?? sample?.heading);
+      if (timeSeconds == null || x == null || y == null || heading == null) return null;
+      return {
+        timeSeconds,
+        x,
+        y,
+        heading,
+        speedKph: finiteNumber(sample?.speedKph) ?? 0,
+        progressMeters: finiteNumber(sample?.progressMeters) ?? 0,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.timeSeconds - b.timeSeconds);
+}
+
+function interpolateTrajectory(trajectory, timeSeconds) {
+  if (trajectory.length === 1 || timeSeconds <= trajectory[0].timeSeconds) return { ...trajectory[0] };
+  const last = trajectory[trajectory.length - 1];
+  if (timeSeconds >= last.timeSeconds) return { ...last };
+  const nextIndex = trajectory.findIndex((sample) => sample.timeSeconds >= timeSeconds);
+  const previous = trajectory[Math.max(0, nextIndex - 1)];
+  const next = trajectory[nextIndex];
+  const span = next.timeSeconds - previous.timeSeconds || 1;
+  const amount = clamp((timeSeconds - previous.timeSeconds) / span, 0, 1);
+  return {
+    timeSeconds,
+    x: lerp(previous.x, next.x, amount),
+    y: lerp(previous.y, next.y, amount),
+    heading: previous.heading + normalizeAngle(next.heading - previous.heading) * amount,
+    speedKph: lerp(previous.speedKph, next.speedKph, amount),
+    progressMeters: lerp(previous.progressMeters, next.progressMeters, amount),
+  };
+}
+
+function finiteNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}

package/src/simulation/rules/collisionSteward.js

@@ -0,0 +1,69 @@
+import { simSpeedToKph } from '../units.js';
+
+export function calculateCollisionPenalties({ first, second, collision = null, rule }) {
+  if (!rule) return [];
+  const severity = collision?.depth ?? 0;
+  const severityThreshold = (rule.minimumSeverity ?? 0) + (rule.relaxedSeverityMargin ?? 0) * (1 - rule.strictness);
+  const impactSpeed = collision?.impactSpeed ?? 0;
+  const impactSpeedThreshold = (rule.minimumImpactSpeed ?? 0) + (rule.relaxedImpactSpeed ?? 0) * (1 - rule.strictness);
+  const atFaultDriverId = collision?.atFaultDriverId ?? null;
+  const aheadDriverId = collision?.aheadDriverId ?? null;
+  const sharedFaultDriverIds = Array.isArray(collision?.sharedFaultDriverIds)
+    ? collision.sharedFaultDriverIds
+    : [];
+
+  if (severity < severityThreshold) return [];
+  if (impactSpeed < impactSpeedThreshold) return [];
+
+  if (sharedFaultDriverIds.length > 0) {
+    return sharedFaultDriverIds
+      .map((driverId) => {
+        const car = first.id === driverId ? first : second.id === driverId ? second : null;
+        if (!car) return null;
+        const other = first.id === driverId ? second : first;
+        return buildCollisionPenalty(car, other, rule, {
+          severity,
+          severityThreshold,
+          impactSpeed,
+          impactSpeedThreshold,
+          aheadDriverId: null,
+          atFaultDriverId: driverId,
+          sharedFault: true,
+          reason: 'Unclear collision responsibility',
+        });
+      })
+      .filter(Boolean);
+  }
+
+  if (!atFaultDriverId || !aheadDriverId) return [];
+
+  const atFault = first.id === atFaultDriverId ? first : second;
+  const other = first.id === atFaultDriverId ? second : first;
+  return [buildCollisionPenalty(atFault, other, rule, {
+    severity,
+    severityThreshold,
+    impactSpeed,
+    impactSpeedThreshold,
+    aheadDriverId,
+    atFaultDriverId,
+  })];
+}
+
+function buildCollisionPenalty(car, other, rule, context) {
+  return {
+    type: 'collision',
+    driverId: car.id,
+    otherCarId: other.id,
+    aheadDriverId: context.aheadDriverId,
+    atFaultDriverId: context.atFaultDriverId,
+    strictness: rule.strictness,
+    penaltySeconds: rule.timePenaltySeconds,
+    consequences: rule.consequences,
+    severity: context.severity,
+    threshold: context.severityThreshold,
+    impactSpeedKph: simSpeedToKph(context.impactSpeed),
+    impactSpeedThresholdKph: simSpeedToKph(context.impactSpeedThreshold),
+    sharedFault: Boolean(context.sharedFault),
+    reason: context.reason ?? 'Avoidable contact with car ahead',
+  };
+}

package/src/simulation/rules/moduleConfig.js

@@ -0,0 +1,72 @@
+import { metersToSimUnits } from '../units.js';
+import { DEFAULT_MODULES } from './ruleDefaults.js';
+import { isPlainObject, clamp01, mergeConfig, nonNegativeInteger, positiveInteger, positiveNumber } from './ruleConfigMerge.js';
+import { normalizePenaltyConfig } from './penaltyConfig.js';
+
+const MODULE_NAMES = Object.keys(DEFAULT_MODULES);
+
+export function normalizeModules(modules, explicitModules = {}) {
+  const next = mergeConfig(DEFAULT_MODULES, modules);
+  const explicitPitSpeed = isPlainObject(explicitModules?.penalties?.pitLaneSpeeding) &&
+    Object.hasOwn(explicitModules.penalties.pitLaneSpeeding, 'speedLimitKph');
+
+  MODULE_NAMES.forEach((name) => {
+    next[name] = {
+      ...next[name],
+      enabled: Boolean(next[name].enabled),
+    };
+  });
+
+  next.pitStops.pitLaneSpeedLimitKph = positiveNumber(next.pitStops.pitLaneSpeedLimitKph, 80);
+  next.pitStops.defaultStopSeconds = positiveNumber(next.pitStops.defaultStopSeconds, 2.8);
+  next.pitStops.variability = {
+    ...DEFAULT_MODULES.pitStops.variability,
+    ...(isPlainObject(next.pitStops.variability) ? next.pitStops.variability : {}),
+  };
+  next.pitStops.variability.enabled = Boolean(next.pitStops.variability.enabled);
+  next.pitStops.variability.perfect = Boolean(next.pitStops.variability.perfect);
+  next.pitStops.variability.speedImpactSeconds = Math.max(
+    0,
+    Number(next.pitStops.variability.speedImpactSeconds) || DEFAULT_MODULES.pitStops.variability.speedImpactSeconds,
+  );
+  next.pitStops.variability.consistencyJitterSeconds = Math.max(
+    0,
+    Number(next.pitStops.variability.consistencyJitterSeconds) || DEFAULT_MODULES.pitStops.variability.consistencyJitterSeconds,
+  );
+  next.pitStops.variability.issueChance = clamp01(
+    next.pitStops.variability.issueChance,
+    DEFAULT_MODULES.pitStops.variability.issueChance,
+  );
+  next.pitStops.variability.issueMaxDelaySeconds = Math.max(
+    0,
+    Number(next.pitStops.variability.issueMaxDelaySeconds) || DEFAULT_MODULES.pitStops.variability.issueMaxDelaySeconds,
+  );
+  next.pitStops.maxConcurrentPitLaneCars = positiveInteger(next.pitStops.maxConcurrentPitLaneCars, 3);
+  next.pitStops.minimumPitLaneGapMeters = positiveNumber(next.pitStops.minimumPitLaneGapMeters, 20);
+  next.pitStops.minimumPitLaneGap = metersToSimUnits(next.pitStops.minimumPitLaneGapMeters);
+  next.pitStops.doubleStacking = Boolean(next.pitStops.doubleStacking);
+  next.pitStops.tirePitRequestThresholdPercent = clamp01(
+    Number(next.pitStops.tirePitRequestThresholdPercent) / 100,
+    0.5,
+  ) * 100;
+  next.pitStops.tirePitCommitThresholdPercent = Math.min(
+    next.pitStops.tirePitRequestThresholdPercent,
+    clamp01(Number(next.pitStops.tirePitCommitThresholdPercent) / 100, 0.3) * 100,
+  );
+
+  next.tireStrategy.compounds = Array.isArray(next.tireStrategy.compounds) && next.tireStrategy.compounds.length
+    ? [...next.tireStrategy.compounds]
+    : ['S', 'M', 'H'];
+  next.tireStrategy.mandatoryDistinctDryCompounds = next.tireStrategy.mandatoryDistinctDryCompounds == null
+    ? null
+    : nonNegativeInteger(next.tireStrategy.mandatoryDistinctDryCompounds, 0);
+
+  next.stalledDnf.maxStoppedSeconds = positiveNumber(next.stalledDnf.maxStoppedSeconds, 12);
+  next.stalledDnf.speedThresholdKph = positiveNumber(next.stalledDnf.speedThresholdKph, 5);
+
+  next.penalties = normalizePenaltyConfig(next.penalties);
+  if (!explicitPitSpeed) {
+    next.penalties.pitLaneSpeeding.speedLimitKph = next.pitStops.pitLaneSpeedLimitKph;
+  }
+  return next;
+}

package/src/simulation/rules/penaltyConfig.js

@@ -0,0 +1,99 @@
+import { metersToSimUnits } from '../units.js';
+import { clamp01, nonNegativeInteger, positiveNumber } from './ruleConfigMerge.js';
+
+export const PENALTY_SUBSECTIONS = ['trackLimits', 'collision', 'tireRequirement', 'pitLaneSpeeding'];
+
+const CONSEQUENCE_TYPES = new Set([
+  'warning',
+  'time',
+  'driveThrough',
+  'stopGo',
+  'positionDrop',
+  'gridDrop',
+  'disqualification',
+]);
+
+export function normalizePenaltyConfig(penalties) {
+  const next = {
+    ...penalties,
+    enabled: Boolean(penalties.enabled),
+    stewardStrictness: clamp01(penalties.stewardStrictness, 1),
+  };
+
+  PENALTY_SUBSECTIONS.forEach((name) => {
+    next[name] = {
+      ...penalties[name],
+      strictness: clamp01(penalties[name]?.strictness, 0),
+    };
+  });
+
+  next.trackLimits.warningsBeforePenalty = nonNegativeInteger(next.trackLimits.warningsBeforePenalty, 3);
+  next.trackLimits.consequences = normalizeConsequences(next.trackLimits.consequences, positiveNumber(next.trackLimits.timePenaltySeconds, 5));
+  next.trackLimits.timePenaltySeconds = sumTimeConsequences(next.trackLimits.consequences);
+  next.trackLimits.relaxedMarginMeters = Math.max(0, Number(next.trackLimits.relaxedMarginMeters) || 0);
+  next.trackLimits.relaxedMargin = metersToSimUnits(next.trackLimits.relaxedMarginMeters);
+
+  next.collision.consequences = normalizeConsequences(next.collision.consequences, positiveNumber(next.collision.timePenaltySeconds, 5));
+  next.collision.timePenaltySeconds = sumTimeConsequences(next.collision.consequences);
+  next.collision.minimumSeverity = Math.max(0, Number(next.collision.minimumSeverity) || 0);
+  next.collision.relaxedSeverityMargin = Math.max(0, Number(next.collision.relaxedSeverityMargin) || 0);
+  next.collision.minimumImpactSpeedKph = Math.max(0, Number(next.collision.minimumImpactSpeedKph) || 0);
+  next.collision.relaxedImpactSpeedKph = Math.max(0, Number(next.collision.relaxedImpactSpeedKph) || 0);
+  next.collision.minimumImpactSpeed = metersToSimUnits(next.collision.minimumImpactSpeedKph / 3.6);
+  next.collision.relaxedImpactSpeed = metersToSimUnits(next.collision.relaxedImpactSpeedKph / 3.6);
+  next.tireRequirement.consequences = normalizeConsequences(next.tireRequirement.consequences, positiveNumber(next.tireRequirement.timePenaltySeconds, 10));
+  next.tireRequirement.timePenaltySeconds = sumTimeConsequences(next.tireRequirement.consequences);
+  next.pitLaneSpeeding.speedLimitKph = positiveNumber(next.pitLaneSpeeding.speedLimitKph, 80);
+  next.pitLaneSpeeding.marginKph = Math.max(0, Number(next.pitLaneSpeeding.marginKph) || 0);
+  next.pitLaneSpeeding.relaxedMarginKph = Math.max(0, Number(next.pitLaneSpeeding.relaxedMarginKph) || 0);
+  next.pitLaneSpeeding.consequences = normalizeConsequences(next.pitLaneSpeeding.consequences, positiveNumber(next.pitLaneSpeeding.timePenaltySeconds, 5));
+  next.pitLaneSpeeding.timePenaltySeconds = sumTimeConsequences(next.pitLaneSpeeding.consequences);
+
+  next.enabled = next.enabled || PENALTY_SUBSECTIONS.some((name) => next[name].strictness > 0);
+  return next;
+}
+
+function normalizeConsequences(value, fallbackSeconds) {
+  const source = Array.isArray(value) && value.length
+    ? value
+    : [{ type: 'time', seconds: fallbackSeconds }];
+  const normalized = source
+    .map((consequence) => {
+      const type = CONSEQUENCE_TYPES.has(consequence?.type) ? consequence.type : null;
+      if (!type) return null;
+      if (type === 'time') {
+        return {
+          type,
+          seconds: positiveNumber(consequence.seconds, fallbackSeconds),
+        };
+      }
+      if (type === 'driveThrough') {
+        return {
+          type,
+          conversionSeconds: positiveNumber(consequence.conversionSeconds, 20),
+        };
+      }
+      if (type === 'stopGo') {
+        return {
+          type,
+          seconds: positiveNumber(consequence.seconds, 10),
+          conversionSeconds: positiveNumber(consequence.conversionSeconds, 30),
+        };
+      }
+      if (type === 'positionDrop' || type === 'gridDrop') {
+        return {
+          type,
+          positions: nonNegativeInteger(consequence.positions, 1),
+        };
+      }
+      return { type };
+    })
+    .filter(Boolean);
+  return normalized.length ? normalized : [{ type: 'time', seconds: fallbackSeconds }];
+}
+
+function sumTimeConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'time' ? total + consequence.seconds : total
+  ), 0);
+}

package/src/simulation/rules/penaltyEvents.js

@@ -0,0 +1,18 @@
+export function createPenaltyServedEvent(entry, time) {
+  return {
+    type: 'penalty-served',
+    at: time,
+    penaltyId: entry.id,
+    driverId: entry.driverId,
+    serviceType: entry.serviceType,
+  };
+}
+
+export function createPenaltyCancelledEvent(entry, time) {
+  return {
+    type: 'penalty-cancelled',
+    at: time,
+    penaltyId: entry.id,
+    driverId: entry.driverId,
+  };
+}

package/src/simulation/rules/penaltyLedger.js

@@ -0,0 +1,153 @@
+const DEFAULT_SERVICE_CONVERSION_SECONDS = {
+  driveThrough: 20,
+  stopGo: 30,
+};
+
+export function createPenaltyRecord({ sequence, time, lap, penalty }) {
+  const consequences = normalizePenaltyConsequences(penalty.consequences, penalty.penaltySeconds);
+  const immediatePenaltySeconds = sumTimeConsequences(consequences);
+  const serviceConsequence = consequences.find((consequence) => (
+    consequence.type === 'driveThrough' || consequence.type === 'stopGo'
+  ));
+  const status = penalty.status ?? (serviceConsequence ? 'issued' : 'applied');
+
+  return {
+    id: `penalty-${sequence}`,
+    at: time,
+    lap,
+    ...penalty,
+    status,
+    consequences,
+    penaltySeconds: Number.isFinite(Number(penalty.penaltySeconds))
+      ? Number(penalty.penaltySeconds)
+      : immediatePenaltySeconds,
+    pendingPenaltySeconds: serviceConsequence
+      ? serviceConversionSeconds(serviceConsequence)
+      : 0,
+    serviceType: serviceConsequence?.type ?? null,
+    serviceRequired: Boolean(serviceConsequence),
+    serviceServedAt: null,
+    unserved: false,
+    positionDrop: sumPositionDropConsequences(consequences),
+    gridDrop: sumGridDropConsequences(consequences),
+    disqualified: consequences.some((consequence) => consequence.type === 'disqualification'),
+  };
+}
+
+export function createPenaltyEvent(entry) {
+  return {
+    type: 'penalty',
+    at: entry.at,
+    penaltyId: entry.id,
+    penaltyType: entry.type,
+    driverId: entry.driverId,
+    penaltySeconds: entry.penaltySeconds,
+    status: entry.status,
+    strictness: entry.strictness,
+  };
+}
+
+export function serializePenalty(penalty) {
+  return { ...penalty };
+}
+
+export function servePenaltyRecord(penalty, time) {
+  if (!penalty || penalty.status === 'cancelled') return penalty;
+  if (!penalty.serviceRequired) return penalty;
+  penalty.status = 'served';
+  penalty.serviceServedAt = time;
+  penalty.unserved = false;
+  return penalty;
+}
+
+export function getPitServicePenaltySeconds(penalty) {
+  if (!penalty || penalty.status === 'cancelled' || penalty.status === 'served') return 0;
+  if (penalty.serviceRequired && penalty.status === 'issued') {
+    if (penalty.serviceType === 'stopGo') return sumStopGoServiceSeconds(penalty.consequences);
+    if (penalty.serviceType === 'driveThrough') return 0;
+  }
+  if (!penalty.serviceRequired && penalty.status === 'applied') {
+    return sumTimeConsequences(penalty.consequences);
+  }
+  return 0;
+}
+
+export function isPenaltyPitServiceable(penalty) {
+  if (!penalty || penalty.status === 'cancelled' || penalty.status === 'served') return false;
+  if (penalty.serviceRequired && penalty.status === 'issued') return true;
+  return !penalty.serviceRequired &&
+    penalty.status === 'applied' &&
+    getPitServicePenaltySeconds(penalty) > 0;
+}
+
+export function servePitPenaltyRecord(penalty, time) {
+  if (!isPenaltyPitServiceable(penalty)) return penalty;
+  penalty.status = 'served';
+  penalty.serviceServedAt = time;
+  penalty.unserved = false;
+  penalty.penaltySeconds = 0;
+  penalty.pendingPenaltySeconds = 0;
+  return penalty;
+}
+
+export function cancelPenaltyRecord(penalty, time) {
+  if (!penalty) return penalty;
+  penalty.status = 'cancelled';
+  penalty.cancelledAt = time;
+  penalty.penaltySeconds = 0;
+  penalty.pendingPenaltySeconds = 0;
+  penalty.positionDrop = 0;
+  penalty.gridDrop = 0;
+  penalty.disqualified = false;
+  penalty.unserved = false;
+  return penalty;
+}
+
+export function applyUnservedServicePenalty(penalty, time) {
+  if (!penalty || penalty.status !== 'issued' || !penalty.serviceRequired) return penalty;
+  penalty.status = 'applied';
+  penalty.appliedAt = time;
+  penalty.unserved = true;
+  penalty.penaltySeconds += penalty.pendingPenaltySeconds;
+  return penalty;
+}
+
+export function isPenaltyActive(penalty) {
+  return penalty?.status !== 'cancelled';
+}
+
+function normalizePenaltyConsequences(consequences, fallbackSeconds = 0) {
+  if (Array.isArray(consequences) && consequences.length) return consequences.map((consequence) => ({ ...consequence }));
+  const seconds = Number(fallbackSeconds) || 0;
+  return seconds > 0 ? [{ type: 'time', seconds }] : [];
+}
+
+function sumTimeConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'time' ? total + (Number(consequence.seconds) || 0) : total
+  ), 0);
+}
+
+function sumStopGoServiceSeconds(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'stopGo' ? total + (Number(consequence.seconds) || 0) : total
+  ), 0);
+}
+
+function sumPositionDropConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'positionDrop' ? total + Math.max(0, Math.floor(Number(consequence.positions) || 0)) : total
+  ), 0);
+}
+
+function sumGridDropConsequences(consequences) {
+  return consequences.reduce((total, consequence) => (
+    consequence.type === 'gridDrop' ? total + Math.max(0, Math.floor(Number(consequence.positions) || 0)) : total
+  ), 0);
+}
+
+function serviceConversionSeconds(consequence) {
+  return Number.isFinite(Number(consequence.conversionSeconds))
+    ? Math.max(0, Number(consequence.conversionSeconds))
+    : DEFAULT_SERVICE_CONVERSION_SECONDS[consequence.type] ?? 0;
+}

package/src/simulation/rules/penaltyStats.js

@@ -0,0 +1,26 @@
+import { isPenaltyActive } from './penaltyLedger.js';
+
+export function createEmptyPenaltyStats() {
+  return {
+    seconds: 0,
+    positionDrop: 0,
+    disqualified: false,
+  };
+}
+
+export function getPenaltyStats(statsByDriver, driverId) {
+  return statsByDriver.get(driverId) ?? createEmptyPenaltyStats();
+}
+
+export function buildPenaltyStatsByDriver(penalties = []) {
+  const byDriver = new Map();
+  penalties.forEach((penalty) => {
+    if (!penalty?.driverId || !isPenaltyActive(penalty)) return;
+    const stats = byDriver.get(penalty.driverId) ?? createEmptyPenaltyStats();
+    stats.seconds += Number(penalty.penaltySeconds) || 0;
+    stats.positionDrop += Number(penalty.positionDrop) || 0;
+    stats.disqualified = stats.disqualified || Boolean(penalty.disqualified);
+    byDriver.set(penalty.driverId, stats);
+  });
+  return byDriver;
+}

package/src/simulation/rules/pitLaneSpeedingSteward.js

@@ -0,0 +1,71 @@
+const SPEED_LIMITED_PIT_PARTS = new Set(['fast-lane', 'working-lane', 'service-box', 'garage-box']);
+
+export function calculatePitLaneSpeedingReview({ car, rule, stewardState }) {
+  const current = stewardState ?? { active: false, violations: 0 };
+  if (!rule) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const speedKph = Number(car.speedKph);
+  const pitLanePart = car.trackState?.pitLanePart ?? car.pitLanePart;
+  const inLimitedPitLane = Boolean(car.trackState?.inPitLane) && SPEED_LIMITED_PIT_PARTS.has(pitLanePart);
+  const marginKph = (Number(rule.marginKph) || 0) + ((Number(rule.relaxedMarginKph) || 0) * (1 - rule.strictness));
+  const speedLimitKph = Number(rule.speedLimitKph) || 80;
+  const excessKph = speedKph - speedLimitKph;
+  const isViolation = inLimitedPitLane && excessKph > marginKph;
+
+  if (!isViolation) {
+    return {
+      nextState: { ...current, active: false },
+      event: null,
+      penalty: null,
+    };
+  }
+
+  if (current.active) {
+    return {
+      nextState: current,
+      event: null,
+      penalty: null,
+    };
+  }
+
+  const violationCount = current.violations + 1;
+  const nextState = {
+    active: true,
+    violations: violationCount,
+  };
+  const event = {
+    type: 'pit-lane-speeding',
+    carId: car.id,
+    violationCount,
+    speedKph,
+    speedLimitKph,
+    excessKph,
+    pitLanePart,
+    strictness: rule.strictness,
+  };
+
+  return {
+    nextState,
+    event,
+    penalty: {
+      type: 'pit-lane-speeding',
+      driverId: car.id,
+      strictness: rule.strictness,
+      penaltySeconds: rule.timePenaltySeconds,
+      consequences: rule.consequences,
+      violationCount,
+      speedKph,
+      speedLimitKph,
+      excessKph,
+      marginKph,
+      pitLanePart,
+      reason: 'Exceeded pit lane speed limit',
+    },
+  };
+}

package/src/simulation/rules/ruleConfigMerge.js

@@ -0,0 +1,41 @@
+export function isPlainObject(value) {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function clone(value) {
+  if (Array.isArray(value)) return value.map((item) => clone(item));
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, clone(item)]));
+}
+
+export function mergeConfig(base, override) {
+  if (!isPlainObject(override)) return clone(base);
+  const next = clone(base);
+  Object.entries(override).forEach(([key, value]) => {
+    next[key] = isPlainObject(value) && isPlainObject(next[key])
+      ? mergeConfig(next[key], value)
+      : clone(value);
+  });
+  return next;
+}
+
+export function clamp01(value, fallback = 0) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(0, Math.min(1, numeric));
+}
+
+export function positiveNumber(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+}
+
+export function nonNegativeInteger(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric >= 0 ? Math.floor(numeric) : fallback;
+}
+
+export function positiveInteger(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) && numeric > 0 ? Math.floor(numeric) : fallback;
+}