@inventure71/paddockjs 4.2.0 → 4.3.0

package/src/environment/evaluationTracker.js

@@ -0,0 +1,100 @@
+import { simUnitsToMeters } from '../simulation/units.js';
+import { isEnvironmentCarOffTrack } from './metrics.js';
+import { isEnvironmentContactEvent, writeEventDriverIds } from './events.js';
+
+export function createEvaluationTracker(initialResult, { lapScope = 'since-start' } = {}) {
+  if (!initialResult?.state?.snapshot) {
+    throw new Error('PaddockJS environment evaluation tracker requires result.state.snapshot; use result.stateOutput "minimal" or "full".');
+  }
+  const initialCars = carsById(initialResult.state.snapshot);
+  const metrics = Object.fromEntries(initialResult.info.controlledDrivers.map((driverId) => {
+    const car = initialCars.get(driverId);
+    const offTrack = isEnvironmentCarOffTrack(car);
+    return [driverId, {
+      distanceMeters: 0,
+      lapProgressMeters: lapProgressMetersFromSnapshotCar(car),
+      offTrackSteps: offTrack ? 1 : 0,
+      contactCount: 0,
+      recoverySuccess: false,
+      passCount: 0,
+      lapTimeSeconds: lapScope === 'include-history' && completedLaps(car) > 0 ? recordedLapTime(car) : null,
+      previousCompletedLaps: completedLaps(car),
+      startedOffTrack: offTrack,
+      startPosition: car?.rank ?? null,
+      bestPosition: car?.rank ?? null,
+      startDistanceMeters: cumulativeDistanceMetersFromSnapshotCar(car),
+    }];
+  }));
+
+  return {
+    update(result) {
+      const currentCars = carsById(result.state.snapshot);
+      result.info.controlledDrivers.forEach((driverId) => {
+        const car = currentCars.get(driverId);
+        const entry = metrics[driverId];
+        if (!car || !entry) return;
+        entry.distanceMeters = Math.max(0, cumulativeDistanceMetersFromSnapshotCar(car) - entry.startDistanceMeters);
+        entry.lapProgressMeters = lapProgressMetersFromSnapshotCar(car);
+        const offTrack = isEnvironmentCarOffTrack(car);
+        if (offTrack) entry.offTrackSteps += 1;
+        if (entry.startedOffTrack && !offTrack) entry.recoverySuccess = true;
+        if (Number.isFinite(car.rank)) {
+          entry.bestPosition = entry.bestPosition == null ? car.rank : Math.min(entry.bestPosition, car.rank);
+          entry.passCount = entry.startPosition == null ? 0 : Math.max(0, entry.startPosition - entry.bestPosition);
+        }
+        const currentCompletedLaps = completedLaps(car);
+        const newCompletion = currentCompletedLaps > entry.previousCompletedLaps;
+        if (newCompletion && entry.lapTimeSeconds == null) {
+          entry.lapTimeSeconds = recordedLapTime(car);
+        }
+        entry.previousCompletedLaps = currentCompletedLaps;
+      });
+      const eventDriverIds = [];
+      result.events.forEach((event) => {
+        if (!isEnvironmentContactEvent(event)) return;
+        writeEventDriverIds(eventDriverIds, event).forEach((driverId) => {
+          if (metrics[driverId]) metrics[driverId].contactCount += 1;
+        });
+      });
+    },
+    finish() {
+      return Object.fromEntries(Object.entries(metrics).map(([driverId, entry]) => [
+        driverId,
+        {
+          distanceMeters: entry.distanceMeters,
+          lapProgressMeters: entry.lapProgressMeters,
+          offTrackSteps: entry.offTrackSteps,
+          contactCount: entry.contactCount,
+          recoverySuccess: entry.recoverySuccess,
+          passCount: entry.passCount,
+          lapTimeSeconds: entry.lapTimeSeconds,
+        },
+      ]));
+    },
+  };
+}
+
+function cumulativeDistanceMetersFromSnapshotCar(car) {
+  const distance = Number(car?.distanceMeters ?? car?.raceDistanceMeters);
+  if (Number.isFinite(distance)) return distance;
+  return simUnitsToMeters(car?.raceDistance ?? 0);
+}
+
+function lapProgressMetersFromSnapshotCar(car) {
+  const progressMeters = Number(car?.lapProgressMeters ?? car?.progressMeters);
+  if (Number.isFinite(progressMeters)) return progressMeters;
+  return simUnitsToMeters(car?.progress ?? 0);
+}
+
+function carsById(snapshot) {
+  return new Map(snapshot.cars.map((car) => [car.id, car]));
+}
+
+function completedLaps(car) {
+  return car?.lapTelemetry?.completedLaps ?? 0;
+}
+
+function recordedLapTime(car) {
+  const duration = car?.lapTelemetry?.lastLapTime;
+  return Number.isFinite(duration) && duration >= 0 ? duration : null;
+}

package/src/environment/events.js

@@ -1,7 +1,30 @@
+export function isEnvironmentContactEvent(event) {
+  return ['collision', 'contact', 'car-contact'].includes(event?.type);
+}
+
 export function collectStepEvents(events = []) {
   return events.map((event) => normalizeEnvironmentEvent(event));
 }
 
+export function writeEventDriverIds(target, event) {
+  target.length = 0;
+  pushEventDriverId(target, event.driverId);
+  pushEventDriverId(target, event.carId);
+  pushEventDriverId(target, event.otherCarId);
+  pushEventDriverId(target, event.primaryDriverId);
+  pushEventDriverId(target, event.otherDriverId);
+  const extraDriverIds = event.driverIds ?? [];
+  for (let index = 0; index < extraDriverIds.length; index += 1) {
+    pushEventDriverId(target, extraDriverIds[index]);
+  }
+  return target;
+}
+
+function pushEventDriverId(target, driverId) {
+  if (!driverId || target.includes(driverId)) return;
+  target.push(driverId);
+}
+
 function normalizeEnvironmentEvent(event) {
   if (event.type === 'contact') {
     return {

package/src/environment/index.d.ts

@@ -1,106 +1,17 @@
-export type TireCompound = 'S' | 'M' | 'H';
-export type PaddockPhysicsMode = 'arcade' | 'advanced';
-export type PaddockProceduralTrackProfile = 'race' | 'training-short' | 'training-medium' | 'training-technical';
-
-export interface PaddockProceduralTrackOptions {
-  profile?: PaddockProceduralTrackProfile;
-  minLengthMeters?: number;
-  maxLengthMeters?: number;
-  startStraightMeters?: number;
-  includePitLane?: boolean;
-  length?: {
-    minMeters?: number;
-    maxMeters?: number;
-  };
-  startStraight?: {
-    gridMeters?: number;
-    exitMeters?: number;
-    blendMeters?: number;
-    lockExtraMeters?: number;
-  };
-  pitLane?: {
-    enabled?: boolean;
-  };
-  shape?: {
-    scale?: number;
-    cornerDensity?: number;
-    variation?: number;
-  };
-  validation?: {
-    minClearanceMultiplier?: number;
-    minShapeVariation?: number;
-    minNonAdjacentArcMeters?: number;
-    maxLocalTurnRadians?: number;
-    maxSampleHeadingDeltaRadians?: number;
-  };
-  attempts?: {
-    primary?: number;
-    fallback?: number;
-  };
-}
+import type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from '../data/trackTypes.js';
+import type { TireCompound, SimulatorDriver, ChampionshipEntryBlueprint } from '../data/entryTypes.js';
+export type { PaddockProceduralTrackProfile, PaddockProceduralTrackOptions, PaddockTrackPoint, PaddockDrsZone, PaddockResolvedProceduralTrackOptions, PaddockProceduralTrack } from '../data/trackTypes.js';
+export type { TireCompound, SimulatorDriver, ChampionshipEntryBlueprint } from '../data/entryTypes.js';
 
-export interface PaddockTrackPoint {
-  x: number;
-  y: number;
-}
+import type { TeamData } from '../data/teamTypes.js';
 
-export interface PaddockDrsZone {
-  id: string;
-  startRatio: number;
-  endRatio: number;
-}
-
-export interface PaddockResolvedProceduralTrackOptions {
-  profile: PaddockProceduralTrackProfile;
-  length: {
-    min: number;
-    max: number;
-  };
-  startStraight: {
-    grid: number;
-    exit: number;
-    blend: number;
-    lockExtra: number;
-  };
-  pitLane: {
-    enabled: boolean;
-  };
-  shape: {
-    scale: number;
-    cornerDensity: number;
-    variation: number;
-  };
-  validation: {
-    minClearanceMultiplier: number;
-    minShapeVariation: number;
-    minNonAdjacentArcDistance: number;
-    maxLocalTurnRadians: number;
-    maxSampleHeadingDeltaRadians: number;
-  };
-  attempts: {
-    primary: number;
-    fallback: number;
-  };
-  cacheKey: string;
-  [key: string]: unknown;
-}
+export type {
+  PaddockPitCrewStats,
+  PaddockThemeSelector,
+  TeamData,
+} from '../data/teamTypes.js';
 
-export interface PaddockProceduralTrack {
-  name: string;
-  width: number;
-  kerbWidth: number;
-  gravelWidth: number;
-  runoffWidth: number;
-  barrierWidth: number;
-  sampleCount: number;
-  seed?: number;
-  curveInterpolation?: string;
-  centerlineControls?: readonly PaddockTrackPoint[];
-  drsZones?: readonly PaddockDrsZone[] | null;
-  pitLane?: { enabled?: boolean } | null;
-  generationOptions?: PaddockResolvedProceduralTrackOptions;
-  [key: string]: unknown;
-}
+export type PaddockPhysicsMode = 'arcade' | 'advanced';
 
 export type PaddockStabilityState = 'stable' | 'understeer' | 'oversteer' | 'spin-risk' | 'destroyed';
 export type PaddockPitIntent = 0 | 1 | 2;
@@ -172,45 +83,6 @@ export interface PaddockReplayGhostSnapshot {
   };
 }
 
-export interface TeamData {
-  id?: string;
-  name?: string;
-  color?: string;
-  icon?: string;
-  pitCrew?: PaddockPitCrewStats;
-  pitCrewStats?: PaddockPitCrewStats;
-}
-
-export interface PaddockPitCrewStats {
-  speed?: number;
-  consistency?: number;
-  reliability?: number;
-}
-
-export interface SimulatorDriver {
-  id: string;
-  name: string;
-  color: string;
-  link?: string;
-  icon?: string;
-  code?: string;
-  timingName?: string;
-  tire?: TireCompound;
-  raceData?: string[];
-  customFields?: Array<{ label: string; value: string }> | Record<string, string>;
-  team?: TeamData | null;
-  driverNumber?: number;
-}
-
-export interface ChampionshipEntryBlueprint {
-  driverId: string;
-  driverNumber?: number;
-  timingName?: string;
-  driver?: unknown;
-  vehicle?: unknown;
-  team?: TeamData;
-}
-
 export interface RaceEvent {
   type: string;
   at?: number;
@@ -731,6 +603,8 @@ export type PaddockPolicyLike =
   | { predict(observation: PaddockDriverObservation, context: Record<string, unknown>): PaddockAction };
 
 export interface PaddockDriverControllerContext {
+  /** Generation cancellation signal; Paddock-owned loops always supply it. */
+  signal?: AbortSignal;
   runtime: PaddockControllerRuntime;
   mode: string;
   actionRepeat: number;
@@ -932,7 +806,13 @@ export function createRolloutTransition(
 ): PaddockRolloutTransition;
 export const ENVIRONMENT_SCENARIO_PRESETS: readonly PaddockScenarioPreset[];
 export const DEFAULT_EVALUATION_CASES: readonly PaddockEvaluationCase[];
-export function createEvaluationTracker(initialResult: PaddockEnvironmentSnapshotResult): {
+export type PaddockEvaluationLapScope = 'since-start' | 'include-history';
+
+export interface PaddockEvaluationTrackerOptions {
+  lapScope?: PaddockEvaluationLapScope;
+}
+
+export function createEvaluationTracker(initialResult: PaddockEnvironmentSnapshotResult, options?: PaddockEvaluationTrackerOptions): {
   update(result: PaddockEnvironmentSnapshotResult): void;
   finish(): Record<string, PaddockEvaluationDriverMetrics>;
 };
@@ -940,6 +820,7 @@ export function runEnvironmentEvaluation(options: {
   baseOptions: PaddockEnvironmentOptions;
   policy: PaddockPolicyLike;
   cases?: PaddockEvaluationCase[];
+  lapScope?: PaddockEvaluationLapScope;
   createEnvironment?: (options: PaddockEnvironmentOptions) => PaddockEnvironment;
 }): PaddockEvaluationReport;
 export function createEnvironmentWorkerProtocol(env: PaddockEnvironment): PaddockEnvironmentWorkerProtocol;

package/src/environment/metrics.js

@@ -1,3 +1,5 @@
+import { isEnvironmentContactEvent, writeEventDriverIds } from './events.js';
+export { isEnvironmentContactEvent } from './events.js';
 import { normalizeAngle } from '../simulation/simMath.js';
 import { pointAt } from '../simulation/track/trackModel.js';
 import { simUnitsToMeters } from '../simulation/units.js';
@@ -26,10 +28,6 @@ export function isEnvironmentCarOffTrack(car) {
   return isOffTrack(car, classifyWheels(car));
 }
 
-export function isEnvironmentContactEvent(event) {
-  return ['collision', 'contact', 'car-contact'].includes(event?.type);
-}
-
 export function buildDriverMetrics({ snapshot, previousSnapshot = null, options, events = [], scratch = null }) {
   const previousById = carsByIdForMetrics(previousSnapshot, scratch, 'previousCarsById');
   const currentById = carsByIdForMetrics(snapshot, scratch, 'currentCarsById');
@@ -179,14 +177,7 @@ function contactCountsByDriver(events, scratch = null) {
   counts.clear();
   events.forEach((event) => {
     if (!isEnvironmentContactEvent(event)) return;
-    eventDriverIds.length = 0;
-    pushEventDriverId(eventDriverIds, event.driverId);
-    pushEventDriverId(eventDriverIds, event.carId);
-    pushEventDriverId(eventDriverIds, event.otherCarId);
-    const extraDriverIds = event.driverIds ?? [];
-    for (let index = 0; index < extraDriverIds.length; index += 1) {
-      pushEventDriverId(eventDriverIds, extraDriverIds[index]);
-    }
+    writeEventDriverIds(eventDriverIds, event);
     for (let index = 0; index < eventDriverIds.length; index += 1) {
       const driverId = eventDriverIds[index];
       counts.set(driverId, (counts.get(driverId) ?? 0) + 1);
@@ -195,8 +186,3 @@ function contactCountsByDriver(events, scratch = null) {
   eventDriverIds.length = 0;
   return counts;
 }
-
-function pushEventDriverId(target, driverId) {
-  if (!driverId || target.includes(driverId)) return;
-  target.push(driverId);
-}

package/src/environment/observationSchema.js

@@ -0,0 +1,104 @@
+export const MODEL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
+
+export function buildObservationVectorSchema({
+  profile = 'default',
+  contactPatchCount = 4,
+  lookaheadCount = 0,
+  rayCount = 0,
+  rayChannels = [],
+  nearbyCount = 0,
+}) {
+  const includePhysicalDriverSenses = profile === 'physical-driver';
+  const schema = [
+    { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
+    { name: 'self.speedMetersPerSecond', unit: 'm/s', scale: 'fixed:120' },
+    { name: 'self.steeringAngleRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.throttle', scale: '0..1' },
+    { name: 'self.brake', scale: '0..1' },
+    { name: 'self.lateralG', scale: 'fixed:8g' },
+    { name: 'self.longitudinalG', scale: 'fixed:6g' },
+    { name: 'self.gripUsage', scale: '0..2' },
+    { name: 'self.slipAngleRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.tractionLimited', scale: 'boolean' },
+    { name: 'self.lapProgressRatio', scale: '0..1' },
+    { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
+    { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
+    { name: 'self.onTrack', scale: 'boolean' },
+    { name: 'self.inPitLane', scale: 'boolean' },
+    { name: 'self.tireEnergy', scale: '0..100' },
+    { name: 'self.pitIntent', scale: '0..2' },
+    { name: 'self.pitStopActive', scale: 'boolean' },
+    { name: 'race.positionNormalized', scale: '0..1' },
+    { name: 'race.raceModeGreen', scale: 'boolean' },
+    { name: 'race.raceModeSafetyCar', scale: 'boolean' },
+    { name: 'race.redFlag', scale: 'boolean' },
+    { name: 'race.pitLaneOpen', scale: 'boolean' },
+    { name: 'track.curvature', scale: 'track-curvature' },
+  ];
+  if (includePhysicalDriverSenses) {
+    schema.push(
+      { name: 'self.yawRateRadiansPerSecond', unit: 'rad/s', scale: 'fixed:pi' },
+      { name: 'trackRelation.leftBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.rightBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
+      { name: 'trackRelation.legalWidthMeters', unit: 'm', scale: 'fixed:meters' },
+    );
+    for (let index = 0; index < contactPatchCount; index += 1) {
+      schema.push(
+        { name: `contactPatches[${index}].present`, scale: 'boolean' },
+        { name: `contactPatches[${index}].surfaceCode`, scale: 'surface-code' },
+        { name: `contactPatches[${index}].onLegalSurface`, scale: 'boolean' },
+        { name: `contactPatches[${index}].signedOffsetMeters`, unit: 'm', scale: 'fixed:meters' },
+        { name: `contactPatches[${index}].crossTrackErrorMeters`, unit: 'm', scale: 'fixed:meters' },
+      );
+    }
+  }
+  for (let index = 0; index < lookaheadCount; index += 1) {
+    schema.push(
+      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
+      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
+    );
+  }
+  for (let index = 0; index < rayCount; index += 1) {
+    schema.push(
+      { name: `rays[${index}].track.distanceRatio`, scale: '0..1' },
+      { name: `rays[${index}].track.hit`, scale: 'boolean' },
+      { name: `rays[${index}].track.kindExit`, scale: 'boolean' },
+      { name: `rays[${index}].track.kindEntry`, scale: 'boolean' },
+      { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
+      { name: `rays[${index}].car.hit`, scale: 'boolean' },
+      { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+      { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
+    );
+    MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
+      if (rayChannels?.includes?.(channel)) {
+        schema.push(
+          { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
+          { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
+        );
+      }
+    });
+  }
+  for (let index = 0; index < nearbyCount; index += 1) {
+    schema.push(
+      { name: `nearbyCars[${index}].present`, scale: 'boolean' },
+      { name: `nearbyCars[${index}].relativeForwardRatio`, scale: '-1..1' },
+      { name: `nearbyCars[${index}].relativeRightRatio`, scale: '-1..1' },
+      { name: `nearbyCars[${index}].relativeDistanceRatio`, scale: '0..1' },
+      { name: `nearbyCars[${index}].relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
+      { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
+      { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
+      { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
+      { name: `nearbyCars[${index}].entityTypeReplayGhost`, scale: 'boolean' },
+    );
+    if (includePhysicalDriverSenses) {
+      schema.push(
+        { name: `nearbyCars[${index}].behind`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].closingRateMetersPerSecond`, unit: 'm/s', scale: 'fixed:100' },
+        { name: `nearbyCars[${index}].timeToContactSeconds`, unit: 's', scale: 'fixed:10' },
+        { name: `nearbyCars[${index}].leftOverlap`, scale: 'boolean' },
+        { name: `nearbyCars[${index}].rightOverlap`, scale: 'boolean' },
+      );
+    }
+  }
+  return schema;
+}

package/src/environment/observationVector.js

@@ -1,33 +1,8 @@
-const MODEL_RAY_SURFACE_CHANNELS = Object.freeze(['kerb', 'illegalSurface']);
+import { appendRayVectorValues } from './sensors/rayOutputs.js';
+import { buildObservationVectorSchema, MODEL_RAY_SURFACE_CHANNELS } from './observationSchema.js';
 
 export function buildObservationVector(source, sensors, { includeSchema = true, vectorType = 'array' } = {}) {
   const includePhysicalDriverSenses = source.profile === 'physical-driver';
-  const schema = includeSchema ? [
-    { name: 'self.speedKph', unit: 'kph', scale: 'fixed:400' },
-    { name: 'self.speedMetersPerSecond', unit: 'm/s', scale: 'fixed:120' },
-    { name: 'self.steeringAngleRadians', unit: 'rad', scale: 'fixed:pi' },
-    { name: 'self.throttle', scale: '0..1' },
-    { name: 'self.brake', scale: '0..1' },
-    { name: 'self.lateralG', scale: 'fixed:8g' },
-    { name: 'self.longitudinalG', scale: 'fixed:6g' },
-    { name: 'self.gripUsage', scale: '0..2' },
-    { name: 'self.slipAngleRadians', unit: 'rad', scale: 'fixed:pi' },
-    { name: 'self.tractionLimited', scale: 'boolean' },
-    { name: 'self.lapProgressRatio', scale: '0..1' },
-    { name: 'self.trackOffsetMeters', unit: 'm', scale: 'fixed:meters' },
-    { name: 'self.trackHeadingErrorRadians', unit: 'rad', scale: 'fixed:pi' },
-    { name: 'self.onTrack', scale: 'boolean' },
-    { name: 'self.inPitLane', scale: 'boolean' },
-    { name: 'self.tireEnergy', scale: '0..100' },
-    { name: 'self.pitIntent', scale: '0..2' },
-    { name: 'self.pitStopActive', scale: 'boolean' },
-    { name: 'race.positionNormalized', scale: '0..1' },
-    { name: 'race.raceModeGreen', scale: 'boolean' },
-    { name: 'race.raceModeSafetyCar', scale: 'boolean' },
-    { name: 'race.redFlag', scale: 'boolean' },
-    { name: 'race.pitLaneOpen', scale: 'boolean' },
-    { name: 'track.curvature', scale: 'track-curvature' },
-  ] : null;
   const vector = [
     source.self.speedKph / 400,
     source.self.speedMetersPerSecond / 120,
@@ -55,26 +30,13 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
     source.track.curvature ?? 0,
   ];
   if (includePhysicalDriverSenses) {
-    pushSchema(schema,
-      { name: 'self.yawRateRadiansPerSecond', unit: 'rad/s', scale: 'fixed:pi' },
-      { name: 'trackRelation.leftBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
-      { name: 'trackRelation.rightBoundaryMeters', unit: 'm', scale: 'fixed:meters' },
-      { name: 'trackRelation.legalWidthMeters', unit: 'm', scale: 'fixed:meters' },
-    );
     vector.push(
       source.self.yawRateRadiansPerSecond / Math.PI,
       source.trackRelation.leftBoundaryMeters,
       source.trackRelation.rightBoundaryMeters,
       source.trackRelation.legalWidthMeters,
     );
-    source.contactPatches.forEach((patch, index) => {
-      pushSchema(schema,
-        { name: `contactPatches[${index}].present`, scale: 'boolean' },
-        { name: `contactPatches[${index}].surfaceCode`, scale: 'surface-code' },
-        { name: `contactPatches[${index}].onLegalSurface`, scale: 'boolean' },
-        { name: `contactPatches[${index}].signedOffsetMeters`, unit: 'm', scale: 'fixed:meters' },
-        { name: `contactPatches[${index}].crossTrackErrorMeters`, unit: 'm', scale: 'fixed:meters' },
-      );
+    source.contactPatches.forEach((patch) => {
       vector.push(
         patch.present ? 1 : 0,
         patch.surfaceCode / 5,
@@ -84,58 +46,21 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
       );
     });
   }
-  source.track.lookahead.forEach((sample, index) => {
-    pushSchema(schema,
-      { name: `track.lookahead[${index}].curvature`, scale: 'track-curvature' },
-      { name: `track.lookahead[${index}].headingDeltaRadians`, unit: 'rad', scale: 'fixed:pi' },
-    );
+  source.track.lookahead.forEach((sample) => {
     vector.push(sample.curvature ?? 0, (sample.headingDeltaRadians ?? 0) / Math.PI);
   });
   if (typeof source.appendRayVectorValues === 'function') {
     source.appendRayVectorValues(vector);
-  } else if (Array.isArray(source.rayVectorValues)) {
-    source.rayVectorValues.forEach((values, index) => {
-      pushRaySchema(schema, index, sensors);
-      vector.push(...values);
-    });
   } else {
-    source.rays.forEach((ray, index) => {
-      pushRaySchema(schema, index, sensors);
-      vector.push(
-        ratio(ray.track.distanceMeters, ray.lengthMeters),
-        ray.track.hit ? 1 : 0,
-        ray.track.kind === 'exit' ? 1 : 0,
-        ray.track.kind === 'entry' ? 1 : 0,
-        ratio(ray.car.distanceMeters, ray.lengthMeters),
-        ray.car.hit ? 1 : 0,
-        ray.car.relativeSpeedKph / 200,
-        ray.car.targetType === 'replayGhost' ? 1 : 0,
-      );
-      MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
-        if (sensors.rays.channels?.includes?.(channel)) {
-          vector.push(
-            ratio(ray[channel]?.distanceMeters ?? ray.lengthMeters, ray.lengthMeters),
-            ray[channel]?.hit ? 1 : 0,
-          );
-        }
-      });
+    const surfaceChannels = MODEL_RAY_SURFACE_CHANNELS.filter((channel) => sensors.rays.channels?.includes?.(channel));
+    source.rays.forEach((ray) => {
+      appendRayVectorValues(vector, ray.lengthMeters, ray.track, ray.car, ray, surfaceChannels);
     });
   }
   const nearbyLimit = sensors.nearbyCars.enabled ? (sensors.nearbyCars.maxCars ?? source.nearbyCars.length) : 0;
   const nearbyRadius = sensors.nearbyCars.radiusMeters ?? 150;
   for (let index = 0; index < nearbyLimit; index += 1) {
     const nearby = source.nearbyCars[index] ?? null;
-    pushSchema(schema,
-      { name: `nearbyCars[${index}].present`, scale: 'boolean' },
-      { name: `nearbyCars[${index}].relativeForwardRatio`, scale: '-1..1' },
-      { name: `nearbyCars[${index}].relativeRightRatio`, scale: '-1..1' },
-      { name: `nearbyCars[${index}].relativeDistanceRatio`, scale: '0..1' },
-      { name: `nearbyCars[${index}].relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
-      { name: `nearbyCars[${index}].relativeHeadingRadians`, unit: 'rad', scale: 'fixed:pi' },
-      { name: `nearbyCars[${index}].ahead`, scale: 'boolean' },
-      { name: `nearbyCars[${index}].sameLap`, scale: 'boolean' },
-      { name: `nearbyCars[${index}].entityTypeReplayGhost`, scale: 'boolean' },
-    );
     vector.push(
       nearby ? 1 : 0,
       clampRatio((nearby?.relativeForwardMeters ?? 0) / nearbyRadius),
@@ -148,13 +73,6 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
       nearby?.entityType === 'replayGhost' ? 1 : 0,
     );
     if (includePhysicalDriverSenses) {
-      pushSchema(schema,
-        { name: `nearbyCars[${index}].behind`, scale: 'boolean' },
-        { name: `nearbyCars[${index}].closingRateMetersPerSecond`, unit: 'm/s', scale: 'fixed:100' },
-        { name: `nearbyCars[${index}].timeToContactSeconds`, unit: 's', scale: 'fixed:10' },
-        { name: `nearbyCars[${index}].leftOverlap`, scale: 'boolean' },
-        { name: `nearbyCars[${index}].rightOverlap`, scale: 'boolean' },
-      );
       vector.push(
         nearby?.behind ? 1 : 0,
         (nearby?.closingRateMetersPerSecond ?? 0) / 100,
@@ -164,38 +82,21 @@ export function buildObservationVector(source, sensors, { includeSchema = true,
       );
     }
   }
-  return { vector: finalizeVector(vector, vectorType), schema: schema ?? [] };
+  const schema = includeSchema ? buildObservationVectorSchema({
+    profile: source.profile,
+    contactPatchCount: source.contactPatches?.length ?? 0,
+    lookaheadCount: source.track.lookahead.length,
+    rayCount: typeof source.appendRayVectorValues === 'function' ? 0 : source.rays.length,
+    rayChannels: sensors.rays.channels,
+    nearbyCount: nearbyLimit,
+  }) : [];
+  return { vector: finalizeVector(vector, vectorType), schema };
 }
 
 function finalizeVector(vector, vectorType = 'array') {
   return vectorType === 'float32' ? Float32Array.from(vector) : vector;
 }
 
-function pushSchema(schema, ...entries) {
-  if (schema) schema.push(...entries);
-}
-
-function pushRaySchema(schema, index, sensors) {
-  pushSchema(schema,
-    { name: `rays[${index}].track.distanceRatio`, scale: '0..1' },
-    { name: `rays[${index}].track.hit`, scale: 'boolean' },
-    { name: `rays[${index}].track.kindExit`, scale: 'boolean' },
-    { name: `rays[${index}].track.kindEntry`, scale: 'boolean' },
-    { name: `rays[${index}].car.distanceRatio`, scale: '0..1' },
-    { name: `rays[${index}].car.hit`, scale: 'boolean' },
-    { name: `rays[${index}].car.relativeSpeedKph`, unit: 'kph', scale: 'fixed:200' },
-    { name: `rays[${index}].car.targetTypeReplayGhost`, scale: 'boolean' },
-  );
-  MODEL_RAY_SURFACE_CHANNELS.forEach((channel) => {
-    if (sensors.rays.channels?.includes?.(channel)) {
-      pushSchema(schema,
-        { name: `rays[${index}].${channel}.distanceRatio`, scale: '0..1' },
-        { name: `rays[${index}].${channel}.hit`, scale: 'boolean' },
-      );
-    }
-  });
-}
-
 function normalizeLapProgress(source) {
   return ratio(source.self.lapProgressMeters, source.track.lengthMeters || 1);
 }